@pear-protocol/utils 0.8.0 → 1.0.0

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

@@ -1,6 +1,6 @@
 import type { InstrumentId } from '@pear-protocol/types';
 import BigNumber from 'bignumber.js';
-import type { Fill } from '../fills/fill.types';
+import type { AssetPositionBasis, AssetReduction } from './transition.types';
 export type AssetUnrealizedPnL = {
     id: InstrumentId;
     signedQuantity: BigNumber;
@@ -11,27 +11,14 @@ export type AssetUnrealizedPnL = {
 /**
  * One reduction of the position, attributed to the fill that made it.
  *
- * A discriminated union rather than an optional gross, because whether a close could
- * be valued is a property of the replay, not of the fill: a caller cannot tell a
- * priced close from an unpriceable one by looking at the fill alone. `reduceOnly` is
- * an order intent and says nothing about what actually closed, and a 0-price synthetic
- * can equally well OPEN a position — so the walk is the only thing that knows, and it
- * says so here instead of leaving the answer to be guessed downstream.
+ * The reduction itself is exactly what the transition walk reports — the aggregate adds
+ * only the fill it came from, so the two can never describe a close differently.
  *
  * The walk is time-agnostic (a Fill carries no timestamp), so callers that need to
  * filter by time resolve fillId against their own fill records.
  */
-export type AssetClosure = {
-    kind: 'PRICED';
+export type AssetClosure = AssetReduction & {
     fillId: string;
-    gross: BigNumber;
-    entryPrice: BigNumber;
-    exitPrice: BigNumber;
-    closedQuantity: BigNumber;
-} | {
-    kind: 'UNPRICED';
-    fillId: string;
-    closedQuantity: BigNumber;
 };
 export type AssetRealizedPnL = {
     id: InstrumentId;
@@ -41,9 +28,17 @@ export type AssetRealizedPnL = {
     exitQuantity: BigNumber;
     exitNotional: BigNumber;
     exitVwap: BigNumber | null;
+    residualQuantity: BigNumber;
+    residualBasis: AssetPositionBasis;
     totalFees: BigNumber;
     tradeFees: BigNumber;
     pearFees: BigNumber;
     closures: AssetClosure[];
 };
-export type DeployedCapitalFill = Pick<Fill, 'symbol' | 'side' | 'price' | 'quantity'>;
+/** Whether the fill ledger provides a complete deployed-capital denominator. */
+export type DeployedCapitalState = {
+    kind: 'MEASURED';
+    capital: BigNumber;
+} | {
+    kind: 'UNPRICED';
+};

package/dist/asset/compute.d.ts

@@ -1,7 +1,8 @@
 import type { InstrumentId } from '@pear-protocol/types';
 import BigNumber from 'bignumber.js';
 import type { Fill } from '../fills/fill.types';
-import type { AssetRealizedPnL, AssetUnrealizedPnL, DeployedCapitalFill } from './asset.types';
+import type { AssetRealizedPnL, AssetUnrealizedPnL, DeployedCapitalState } from './asset.types';
+import type { AssetFillTransition, AssetTransitionFill } from './transition.types';
 type ExposureMap = Record<InstrumentId, string>;
 type PriceMap = Record<InstrumentId, string>;
 /**
@@ -37,6 +38,41 @@ export declare function computeAssetUndeterminedSizes(fills: Fill[]): Record<Ins
  * Formula: Σ(signedQty × (currentPrice − entryPrice))
  */
 export declare function computeAssetUnrealizedPnLs(exposureMap: ExposureMap, priceMap: PriceMap, fills: Fill[]): AssetUnrealizedPnL[];
+/** One replay of a position's ledger, answering both questions the walk can answer. */
+export type PositionLedgerWalk = {
+    assets: AssetRealizedPnL[];
+    capital: DeployedCapitalState;
+};
+/**
+ * Replay one position's complete ledger once, deriving realized PnL and deployed capital.
+ *
+ * The two answers were previously two replays of the same fills — computeAssetRealizedPnLs
+ * per asset, then computeDeployedCapitalState across the basket — because they accumulate
+ * differently, not because they read different transitions. They read exactly the same ones:
+ * the transition walk keys its running state by symbol, so replaying an asset's fills alone
+ * and replaying them inside the basket produce an identical transition for every fill.
+ *
+ * Folding them also removes the possibility that the position's realized PnL and the capital
+ * it is measured against ever describe different replays of the same ledger.
+ *
+ * Chronological order across legs is required, as it is for the capital walk alone: the peak
+ * is the most every leg ever committed at one time, which only a cross-leg sequence can say.
+ *
+ * @param fills - One position's complete ledger, chronological across every leg.
+ * @returns The per-asset realized rows and the basket's capital state.
+ */
+export declare function walkPositionLedger(fills: Fill[]): PositionLedgerWalk;
+/**
+ * The same walk, over transitions a caller has already computed.
+ *
+ * Exposed because the transition stream is the expensive part and more than one consumer
+ * reads it: a caller that needs both this and its own per-transition output can compute the
+ * stream once and hand it to both, rather than replaying the ledger for each.
+ *
+ * @param transitions - One position's transitions, in the ledger's own order.
+ * @returns The per-asset realized rows and the basket's capital state.
+ */
+export declare function walkPositionTransitions(transitions: readonly AssetFillTransition[]): PositionLedgerWalk;
 /**
  * Compute realized PnL for an entire position.
  *
@@ -46,6 +82,13 @@ export declare function computeAssetRealizedPnLs(fills: Fill[]): AssetRealizedPn
 /**
  * The most cash the position's selected legs had committed at one time.
  *
+ * Returned as a state rather than a number: MEASURED carries that peak, and UNPRICED
+ * refuses the measurement outright once a zero-price fill has opened selected exposure —
+ * an open, an increase, or the opening half of a flip. Cash committed at an unknown price
+ * can only raise the true peak, so a peak built without it would err the return large,
+ * the unsafe direction, and no number is offered instead. A zero-price reduction stays
+ * measurable, because what a close releases depends on the basis held, not the exit price.
+ *
  * 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
@@ -82,5 +125,11 @@ export declare function computeAssetRealizedPnLs(fills: Fill[]): AssetRealizedPn
  * 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 declare function computeDeployedCapitalState(fills: AssetTransitionFill[], assets: Set<string> | undefined): DeployedCapitalState;
+/**
+ * The measurable peak deployed capital, or zero when the ledger contains unpriced basis.
+ *
+ * @deprecated Use computeDeployedCapitalState when zero and unpriced need different handling.
+ */
+export declare function computeDeployedCapital(fills: AssetTransitionFill[], assets: Set<string> | undefined): BigNumber;
 export {};

package/dist/asset/index.d.ts

@@ -1,2 +1,4 @@
-export type { AssetClosure, AssetRealizedPnL, AssetUnrealizedPnL, DeployedCapitalFill } from './asset.types';
+export type { AssetClosure, AssetRealizedPnL, AssetUnrealizedPnL, DeployedCapitalState, } from './asset.types';
 export * from './compute';
+export type { AssetFillTransition, AssetPositionBasis, AssetPositionState, AssetReduction, AssetTransitionFill, } from './transition.types';
+export * from './transitions';

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

@@ -0,0 +1,68 @@
+/** Public contracts for per-fill exposure and cost-basis transitions. */
+import type BigNumber from 'bignumber.js';
+import type { Fill } from '../fills/fill.types';
+/** The fill fields required to derive exposure and cost-basis transitions. */
+export type AssetTransitionFill = Pick<Fill, 'symbol' | 'side' | 'price' | 'quantity'>;
+/** Whether an asset is flat, has a known average basis, or carries unpriceable basis. */
+export type AssetPositionBasis = {
+    kind: 'FLAT';
+} | {
+    kind: 'PRICED';
+    entryPrice: BigNumber;
+} | {
+    kind: 'UNPRICED';
+};
+/** The signed exposure and cost-basis state immediately beside one fill. */
+export type AssetPositionState = {
+    signedQuantity: BigNumber;
+    basis: AssetPositionBasis;
+};
+/**
+ * The priced or unpriceable portion of a fill that reduced existing exposure.
+ *
+ * A discriminated union rather than an optional grossPnl, because whether a close could
+ * be valued is a property of the replay, not of the fill: a caller cannot tell a priced
+ * close from an unpriceable one by looking at the fill alone. `reduceOnly` is an order
+ * intent and says nothing about what actually closed, and a 0-price synthetic can equally
+ * well OPEN a position — so the walk is the only thing that knows, and it says so here
+ * instead of leaving the answer to be guessed downstream.
+ */
+export type AssetReduction = {
+    kind: 'PRICED';
+    quantity: BigNumber;
+    entryPrice: BigNumber;
+    exitPrice: BigNumber;
+    grossPnl: BigNumber;
+} | {
+    kind: 'UNPRICED';
+    quantity: BigNumber;
+};
+type AssetFillTransitionBase<TFill extends AssetTransitionFill> = {
+    fill: TFill;
+    positionBefore: AssetPositionState;
+    positionAfter: AssetPositionState;
+};
+/**
+ * One fill's complete effect on its asset's exposure and basis.
+ *
+ * The original generic fill is retained so callers keep metadata such as timestamp,
+ * provenance, and settlement status without resolving a fill id after the walk.
+ */
+export type AssetFillTransition<TFill extends AssetTransitionFill = Fill> = (AssetFillTransitionBase<TFill> & {
+    kind: 'OPEN';
+    openedQuantity: BigNumber;
+}) | (AssetFillTransitionBase<TFill> & {
+    kind: 'INCREASE';
+    increasedQuantity: BigNumber;
+}) | (AssetFillTransitionBase<TFill> & {
+    kind: 'REDUCE';
+    reduction: AssetReduction;
+}) | (AssetFillTransitionBase<TFill> & {
+    kind: 'CLOSE';
+    reduction: AssetReduction;
+}) | (AssetFillTransitionBase<TFill> & {
+    kind: 'FLIP';
+    reduction: AssetReduction;
+    openedQuantity: BigNumber;
+});
+export {};

package/dist/asset/transitions.d.ts

@@ -0,0 +1,13 @@
+import type { AssetFillTransition, AssetTransitionFill } from './transition.types';
+/**
+ * Replay a complete chronological fill ledger into one transition per input fill.
+ *
+ * Asset state is independent while output order is identical to input order. Equal-time
+ * ordering is therefore the caller's responsibility and is preserved without re-sorting.
+ *
+ * Preconditions, not enforced: every fill carries a positive finite quantity and a
+ * non-negative finite price (price "0" marks an unpriceable synthetic). A zero-quantity
+ * fill is not a valid ledger entry and yields a transition whose kind does not describe
+ * its (absent) exposure effect.
+ */
+export declare function computeFillTransitions<TFill extends AssetTransitionFill>(fills: readonly TFill[]): AssetFillTransition<TFill>[];

package/dist/fills/group.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bucket fills under the position that owns them, preserving the caller's order.
+ *
+ * Two walks depend on that order, so this must never re-sort. The realized-PnL walk reads
+ * each asset's sequence on its own; the deployed-capital walk spans every leg at once, and
+ * so needs the sequence chronological ACROSS legs — the stricter of the two requirements,
+ * and the one a caller is likeliest to break.
+ *
+ * Every history that replays a ledger — portfolio, leaderboard, closed and open positions,
+ * trade history — partitions it here first, so the contract is stated once for all of them.
+ */
+export declare function groupFillsByPosition<Fill extends {
+    positionId: string;
+}>(fills: readonly Fill[]): Map<string, Fill[]>;
+/**
+ * Bucket one position's fills under the asset each traded, preserving the caller's order.
+ *
+ * The per-leg readers walk a bucket in sequence — entry VWAP prices the opens in the order
+ * they happened, and a leg's side falls back to its first fill — so this must never re-sort
+ * either. An asset the walk reported but the ledger never filled has no bucket at all,
+ * which is a real state, not a lookup miss.
+ */
+export declare function groupFillsByAsset<Fill extends {
+    symbol: string;
+}>(fills: readonly Fill[]): Map<string, Fill[]>;

package/dist/fills/index.d.ts

@@ -1,2 +1,3 @@
 export * from './compute';
+export * from './group';
 export * from './realized';

package/dist/index.js

@@ -142,6 +142,192 @@ function computeEntryPriceForAsset(fills) {
 }
 __name(computeEntryPriceForAsset, "computeEntryPriceForAsset");
 
+// src/asset/transitions.ts
+function computeFillTransitions(fills) {
+  const stateByAsset = /* @__PURE__ */ new Map();
+  const transitions = [];
+  for (const fill of fills) {
+    const currentState = stateByAsset.get(fill.symbol) ?? {
+      signedQuantity: ZERO,
+      entryPrice: ZERO,
+      basisUnpriced: false
+    };
+    const result = transitionFill(currentState, fill);
+    transitions.push(result.transition);
+    stateByAsset.set(fill.symbol, result.nextState);
+  }
+  return transitions;
+}
+__name(computeFillTransitions, "computeFillTransitions");
+function transitionFill(currentState, fill) {
+  const price = parse(fill.price);
+  const quantity = parse(fill.quantity);
+  const signedQuantity = signedBySide(quantity, fill.side);
+  const nextSignedQuantity = add(currentState.signedQuantity, signedQuantity);
+  const kind = classifyTransition(currentState.signedQuantity, signedQuantity, nextSignedQuantity);
+  const nextState = advanceState(currentState, kind, price, quantity, nextSignedQuantity);
+  const positionBefore = toPositionState(currentState);
+  const positionAfter = toPositionState(nextState);
+  switch (kind) {
+    case "OPEN":
+      return {
+        nextState,
+        transition: {
+          kind,
+          fill,
+          positionBefore,
+          positionAfter,
+          openedQuantity: quantity
+        }
+      };
+    case "INCREASE":
+      return {
+        nextState,
+        transition: {
+          kind,
+          fill,
+          positionBefore,
+          positionAfter,
+          increasedQuantity: quantity
+        }
+      };
+    case "REDUCE": {
+      const reduction = buildReduction(currentState, price, quantity);
+      return {
+        nextState,
+        transition: {
+          kind,
+          fill,
+          positionBefore,
+          positionAfter,
+          reduction
+        }
+      };
+    }
+    case "CLOSE": {
+      const reduction = buildReduction(currentState, price, quantity);
+      return {
+        nextState,
+        transition: {
+          kind,
+          fill,
+          positionBefore,
+          positionAfter,
+          reduction
+        }
+      };
+    }
+    case "FLIP": {
+      const reduction = buildReduction(currentState, price, quantity);
+      return {
+        nextState,
+        transition: {
+          kind,
+          fill,
+          positionBefore,
+          positionAfter,
+          reduction,
+          openedQuantity: nextSignedQuantity.abs()
+        }
+      };
+    }
+  }
+}
+__name(transitionFill, "transitionFill");
+function classifyTransition(currentQuantity, fillQuantity, nextQuantity) {
+  if (isZero(currentQuantity)) {
+    return "OPEN";
+  }
+  if (isPositive(currentQuantity) === isPositive(fillQuantity)) {
+    return "INCREASE";
+  }
+  if (isZero(nextQuantity)) {
+    return "CLOSE";
+  }
+  if (isPositive(nextQuantity) !== isPositive(currentQuantity)) {
+    return "FLIP";
+  }
+  return "REDUCE";
+}
+__name(classifyTransition, "classifyTransition");
+function buildReduction(currentState, exitPrice, fillQuantity) {
+  const quantity = min(currentState.signedQuantity.abs(), fillQuantity);
+  if (currentState.basisUnpriced || isZero(exitPrice)) {
+    return {
+      kind: "UNPRICED",
+      quantity
+    };
+  }
+  const grossPnl = isPositive(currentState.signedQuantity) ? multiply(quantity, subtract(exitPrice, currentState.entryPrice)) : multiply(quantity, subtract(currentState.entryPrice, exitPrice));
+  return {
+    kind: "PRICED",
+    quantity,
+    entryPrice: currentState.entryPrice,
+    exitPrice,
+    grossPnl
+  };
+}
+__name(buildReduction, "buildReduction");
+function advanceState(currentState, kind, price, fillQuantity, nextSignedQuantity) {
+  switch (kind) {
+    case "OPEN":
+    case "FLIP":
+      return {
+        signedQuantity: nextSignedQuantity,
+        entryPrice: price,
+        basisUnpriced: isZero(price)
+      };
+    case "INCREASE": {
+      const entryNotional = multiply(currentState.entryPrice, currentState.signedQuantity.abs());
+      const addedNotional = multiply(price, fillQuantity);
+      const entryPrice = divide(add(entryNotional, addedNotional), nextSignedQuantity.abs());
+      return {
+        signedQuantity: nextSignedQuantity,
+        entryPrice,
+        basisUnpriced: currentState.basisUnpriced || isZero(price)
+      };
+    }
+    case "REDUCE":
+      return {
+        ...currentState,
+        signedQuantity: nextSignedQuantity
+      };
+    case "CLOSE":
+      return {
+        signedQuantity: ZERO,
+        entryPrice: ZERO,
+        basisUnpriced: false
+      };
+  }
+}
+__name(advanceState, "advanceState");
+function toPositionState(state) {
+  if (isZero(state.signedQuantity)) {
+    return {
+      signedQuantity: state.signedQuantity,
+      basis: {
+        kind: "FLAT"
+      }
+    };
+  }
+  if (state.basisUnpriced) {
+    return {
+      signedQuantity: state.signedQuantity,
+      basis: {
+        kind: "UNPRICED"
+      }
+    };
+  }
+  return {
+    signedQuantity: state.signedQuantity,
+    basis: {
+      kind: "PRICED",
+      entryPrice: state.entryPrice
+    }
+  };
+}
+__name(toPositionState, "toPositionState");
+
 // src/asset/compute.ts
 function computeAssetEntryNotional(signedQuantity, fills) {
   if (signedQuantity.isZero()) {
@@ -207,6 +393,49 @@ function computeAssetUnrealizedPnLs(exposureMap, priceMap, fills) {
   return result;
 }
 __name(computeAssetUnrealizedPnLs, "computeAssetUnrealizedPnLs");
+function walkPositionLedger(fills) {
+  return walkPositionTransitions(computeFillTransitions(fills));
+}
+__name(walkPositionLedger, "walkPositionLedger");
+function walkPositionTransitions(transitions) {
+  const realizedByAsset = /* @__PURE__ */ new Map();
+  const capitalByAsset = /* @__PURE__ */ new Map();
+  let committed = ZERO;
+  let peak = ZERO;
+  let capitalUnpriced = false;
+  for (const transition of transitions) {
+    const { fill, positionAfter } = transition;
+    const realized = realizedByAsset.get(fill.symbol) ?? createAssetRealizedAccumulator();
+    accumulateAssetRealization(realized, transition);
+    realizedByAsset.set(fill.symbol, realized);
+    if (positionAfter.basis.kind === "UNPRICED") {
+      capitalUnpriced = true;
+    }
+    if (capitalUnpriced) {
+      continue;
+    }
+    const previousCapital = capitalByAsset.get(fill.symbol) ?? ZERO;
+    const nextCapital = capitalAfterTransition(transition, previousCapital);
+    committed = add(subtract(committed, previousCapital), nextCapital);
+    capitalByAsset.set(fill.symbol, nextCapital);
+    if (isGreaterThan(committed, peak)) {
+      peak = committed;
+    }
+  }
+  const assets = [
+    ...realizedByAsset
+  ].map(([id, accumulator]) => finalizeAssetRealization(id, accumulator));
+  return {
+    assets,
+    capital: capitalUnpriced ? {
+      kind: "UNPRICED"
+    } : {
+      kind: "MEASURED",
+      capital: peak
+    }
+  };
+}
+__name(walkPositionTransitions, "walkPositionTransitions");
 function computeAssetRealizedPnLs(fills) {
   const bySymbol = /* @__PURE__ */ new Map();
   for (const fill of fills) {
@@ -219,7 +448,7 @@ function computeAssetRealizedPnLs(fills) {
     const tradeFees = assetFills.reduce((acc, fill) => acc.plus(new BigNumber7(fill.tradeFee ?? "0")), ZERO);
     const pearFees = assetFills.reduce((acc, fill) => acc.plus(new BigNumber7(fill.pearFee ?? "0")), ZERO);
     const totalFees = tradeFees.plus(pearFees);
-    const { gross: grossPnl, undeterminedSize, closures, exitQuantity, exitNotional } = walkAssetFills(assetFills);
+    const { gross: grossPnl, undeterminedSize, closures, exitQuantity, exitNotional, residualQuantity, residualBasis } = walkAssetFills(assetFills);
     const netPnl = grossPnl.minus(totalFees);
     const exitVwap = isZero(exitQuantity) ? null : divide(exitNotional, exitQuantity);
     result.push({
@@ -233,106 +462,188 @@ function computeAssetRealizedPnLs(fills) {
       totalFees,
       tradeFees,
       pearFees,
+      residualQuantity,
+      residualBasis,
       closures
     });
   }
   return result;
 }
 __name(computeAssetRealizedPnLs, "computeAssetRealizedPnLs");
-function computeDeployedCapital(fills, assets) {
-  const legs = /* @__PURE__ */ new Map();
+function computeDeployedCapitalState(fills, assets) {
+  const capitalByAsset = /* @__PURE__ */ new Map();
   let committed = ZERO;
   let peak = ZERO;
-  for (const fill of fills) {
+  for (const transition of computeFillTransitions(fills)) {
+    const { fill, positionAfter } = transition;
     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 (positionAfter.basis.kind === "UNPRICED") {
+      return {
+        kind: "UNPRICED"
+      };
+    }
+    const previousCapital = capitalByAsset.get(fill.symbol) ?? ZERO;
+    let nextCapital;
+    switch (transition.kind) {
+      case "OPEN":
+        nextCapital = multiply(transition.openedQuantity, fill.price);
+        break;
+      case "INCREASE":
+        nextCapital = add(previousCapital, multiply(transition.increasedQuantity, fill.price));
+        break;
+      case "REDUCE": {
+        const released = divide(multiply(previousCapital, transition.reduction.quantity), transition.positionBefore.signedQuantity.abs());
+        nextCapital = subtract(previousCapital, released);
+        break;
+      }
+      case "CLOSE":
+        nextCapital = ZERO;
+        break;
+      case "FLIP":
+        nextCapital = multiply(transition.openedQuantity, fill.price);
+        break;
+    }
+    committed = add(subtract(committed, previousCapital), nextCapital);
+    capitalByAsset.set(fill.symbol, nextCapital);
     if (isGreaterThan(committed, peak)) {
       peak = committed;
     }
   }
-  return peak;
+  return {
+    kind: "MEASURED",
+    capital: peak
+  };
+}
+__name(computeDeployedCapitalState, "computeDeployedCapitalState");
+function computeDeployedCapital(fills, assets) {
+  const state = computeDeployedCapitalState(fills, assets);
+  switch (state.kind) {
+    case "MEASURED":
+      return state.capital;
+    case "UNPRICED":
+      return ZERO;
+  }
 }
 __name(computeDeployedCapital, "computeDeployedCapital");
 function walkAssetFills(fills) {
-  let entryPrice = ZERO;
-  let positionSize = ZERO;
-  let basisUnpriced = false;
+  const transitions = computeFillTransitions(fills);
   let gross = ZERO;
   let undeterminedSize = ZERO;
   const closures = [];
   let exitQuantity = ZERO;
   let exitNotional = ZERO;
-  for (const fill of fills) {
-    const price = parse(fill.price);
-    const quantity = parse(fill.quantity);
-    const signedQuantity = signedBySide(quantity, fill.side);
-    const newPositionSize = add(positionSize, signedQuantity);
-    if (!isZero(positionSize) && isPositive(positionSize) !== isPositive(signedQuantity)) {
-      const closedQty = min(positionSize.abs(), signedQuantity.abs());
-      if (basisUnpriced || isZero(price)) {
-        undeterminedSize = add(undeterminedSize, closedQty);
-        closures.push({
-          kind: "UNPRICED",
-          fillId: fill.id,
-          closedQuantity: closedQty
-        });
-      } else {
-        const realized = isPositive(positionSize) ? multiply(closedQty, subtract(price, entryPrice)) : multiply(closedQty, subtract(entryPrice, price));
-        gross = add(gross, realized);
-        closures.push({
-          kind: "PRICED",
-          fillId: fill.id,
-          gross: realized,
-          entryPrice,
-          exitPrice: price,
-          closedQuantity: closedQty
-        });
-        exitQuantity = add(exitQuantity, closedQty);
-        exitNotional = add(exitNotional, multiply(closedQty, price));
-      }
+  let residualQuantity = ZERO;
+  let residualBasis = {
+    kind: "FLAT"
+  };
+  for (const transition of transitions) {
+    residualQuantity = transition.positionAfter.signedQuantity;
+    residualBasis = transition.positionAfter.basis;
+    if (transition.kind === "OPEN" || transition.kind === "INCREASE") {
+      continue;
     }
-    const isSameDirection = !isZero(positionSize) && isPositive(positionSize) === isPositive(signedQuantity);
-    const isFlip = !isZero(positionSize) && !isZero(newPositionSize) && isPositive(newPositionSize) !== isPositive(positionSize);
-    if (isZero(positionSize) || isFlip) {
-      entryPrice = price;
-      basisUnpriced = isZero(price);
-    } else if (isSameDirection) {
-      entryPrice = entryPrice.times(positionSize.abs()).plus(price.times(quantity)).div(newPositionSize.abs());
-      basisUnpriced = basisUnpriced || isZero(price);
+    const { reduction } = transition;
+    closures.push({
+      ...reduction,
+      fillId: transition.fill.id
+    });
+    if (reduction.kind === "UNPRICED") {
+      undeterminedSize = add(undeterminedSize, reduction.quantity);
+      continue;
     }
-    positionSize = newPositionSize;
+    gross = add(gross, reduction.grossPnl);
+    exitQuantity = add(exitQuantity, reduction.quantity);
+    exitNotional = add(exitNotional, multiply(reduction.quantity, reduction.exitPrice));
   }
   return {
     gross,
     undeterminedSize,
     closures,
     exitQuantity,
-    exitNotional
+    exitNotional,
+    residualQuantity,
+    residualBasis
   };
 }
 __name(walkAssetFills, "walkAssetFills");
-function closesAgainstHolding(held, delta) {
-  if (isZero(held) || isPositive(held) === isPositive(delta)) {
-    return ZERO;
+function createAssetRealizedAccumulator() {
+  return {
+    gross: ZERO,
+    undeterminedSize: ZERO,
+    closures: [],
+    exitQuantity: ZERO,
+    exitNotional: ZERO,
+    residualQuantity: ZERO,
+    residualBasis: {
+      kind: "FLAT"
+    },
+    tradeFees: ZERO,
+    pearFees: ZERO
+  };
+}
+__name(createAssetRealizedAccumulator, "createAssetRealizedAccumulator");
+function accumulateAssetRealization(accumulator, transition) {
+  const { fill } = transition;
+  accumulator.tradeFees = add(accumulator.tradeFees, fill.tradeFee ?? "0");
+  accumulator.pearFees = add(accumulator.pearFees, fill.pearFee ?? "0");
+  accumulator.residualQuantity = transition.positionAfter.signedQuantity;
+  accumulator.residualBasis = transition.positionAfter.basis;
+  if (transition.kind === "OPEN" || transition.kind === "INCREASE") {
+    return;
+  }
+  const { reduction } = transition;
+  accumulator.closures.push({
+    ...reduction,
+    fillId: fill.id
+  });
+  if (reduction.kind === "UNPRICED") {
+    accumulator.undeterminedSize = add(accumulator.undeterminedSize, reduction.quantity);
+    return;
   }
-  return min(abs(delta), abs(held));
+  accumulator.gross = add(accumulator.gross, reduction.grossPnl);
+  accumulator.exitQuantity = add(accumulator.exitQuantity, reduction.quantity);
+  accumulator.exitNotional = add(accumulator.exitNotional, multiply(reduction.quantity, reduction.exitPrice));
 }
-__name(closesAgainstHolding, "closesAgainstHolding");
+__name(accumulateAssetRealization, "accumulateAssetRealization");
+function finalizeAssetRealization(id, accumulator) {
+  const totalFees = add(accumulator.tradeFees, accumulator.pearFees);
+  const exitVwap = isZero(accumulator.exitQuantity) ? null : divide(accumulator.exitNotional, accumulator.exitQuantity);
+  return {
+    id,
+    grossPnl: accumulator.gross,
+    netPnl: subtract(accumulator.gross, totalFees),
+    undeterminedSize: accumulator.undeterminedSize,
+    exitQuantity: accumulator.exitQuantity,
+    exitNotional: accumulator.exitNotional,
+    exitVwap,
+    totalFees,
+    tradeFees: accumulator.tradeFees,
+    pearFees: accumulator.pearFees,
+    residualQuantity: accumulator.residualQuantity,
+    residualBasis: accumulator.residualBasis,
+    closures: accumulator.closures
+  };
+}
+__name(finalizeAssetRealization, "finalizeAssetRealization");
+function capitalAfterTransition(transition, previousCapital) {
+  switch (transition.kind) {
+    case "OPEN":
+      return multiply(transition.openedQuantity, transition.fill.price);
+    case "INCREASE":
+      return add(previousCapital, multiply(transition.increasedQuantity, transition.fill.price));
+    case "REDUCE": {
+      const released = divide(multiply(previousCapital, transition.reduction.quantity), transition.positionBefore.signedQuantity.abs());
+      return subtract(previousCapital, released);
+    }
+    case "CLOSE":
+      return ZERO;
+    case "FLIP":
+      return multiply(transition.openedQuantity, transition.fill.price);
+  }
+}
+__name(capitalAfterTransition, "capitalAfterTransition");
 
 // src/basket/compute.ts
 function computeBasketWeightedRatioV1(basket, priceMap) {
@@ -553,6 +864,28 @@ function baseToContracts(base, contractSize) {
   return new BigNumber7(base).div(contractSize);
 }
 __name(baseToContracts, "baseToContracts");
+
+// src/fills/group.ts
+function groupFillsByPosition(fills) {
+  const byPosition = /* @__PURE__ */ new Map();
+  for (const fill of fills) {
+    const positionFills = byPosition.get(fill.positionId) ?? [];
+    positionFills.push(fill);
+    byPosition.set(fill.positionId, positionFills);
+  }
+  return byPosition;
+}
+__name(groupFillsByPosition, "groupFillsByPosition");
+function groupFillsByAsset(fills) {
+  const byAsset = /* @__PURE__ */ new Map();
+  for (const fill of fills) {
+    const assetFills = byAsset.get(fill.symbol) ?? [];
+    assetFills.push(fill);
+    byAsset.set(fill.symbol, assetFills);
+  }
+  return byAsset;
+}
+__name(groupFillsByAsset, "groupFillsByAsset");
 function computeRealizedPnlBySymbol(fills) {
   const bySymbol = groupFillsBySymbol(fills);
   const result = /* @__PURE__ */ new Map();
@@ -653,6 +986,10 @@ function aggregateRealizedPositionState(assetPnLs) {
   };
 }
 __name(aggregateRealizedPositionState, "aggregateRealizedPositionState");
+function sumAttributedFunding(fundingByAsset) {
+  return Object.values(fundingByAsset).reduce((total, assetFunding) => add(total, assetFunding), ZERO);
+}
+__name(sumAttributedFunding, "sumAttributedFunding");
 function computePositionEntryPrice(assetUPnLs) {
   const { totalWeightedPrice, totalWeight } = assetUPnLs.reduce((acc, { signedQuantity, entryPrice }) => {
     const absQuantity = signedQuantity.abs();
@@ -2352,4 +2689,4 @@ function takeVerifier(handoffId, storage) {
 }
 __name(takeVerifier, "takeVerifier");
 
-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 };
+export { BIPS, ZERO, abs, add, aggregateRealizedPositionState, baseToContracts, buildApplicables, compareValue, computeAssetEntryNotional, computeAssetGrossRealizedPnL, computeAssetRealizedPnLs, computeAssetUndeterminedSizes, computeAssetUnrealizedPnL, computeAssetUnrealizedPnLs, computeBasketWeightedRatioV1, computeDeployedCapital, computeDeployedCapitalState, computeEntryPriceForAsset, computeFillTransitions, computeMaxBasketSize, computeMultiQuoteBasketSize, computePositionEntryPrices, computeRealizedPnlBySymbol, computeRealizedPnlFromFills, computeRealizedPositionState, computeSyncPayload, computeUnrealizedPositionState, computeUnrealizedPositionStateFromEntryPrices, configureProxy, contractsToBase, countDecimals, deriveBasketKey, divide, exponentiate, finishXHandoff, generateDeterministicPositionKey, groupFillsByAsset, groupFillsByPosition, 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, sumAttributedFunding, toDecimalString, validateLeverage, validateQuantity, walkPositionLedger, walkPositionTransitions };

package/dist/position/compute.d.ts

@@ -1,4 +1,5 @@
-import type { InstrumentId } from '@pear-protocol/types';
+import type { InstrumentId, PositionTotalFundingPayment } from '@pear-protocol/types';
+import BigNumber from 'bignumber.js';
 import type { AssetRealizedPnL } from '../asset/asset.types';
 import type { Fill } from '../fills/fill.types';
 import type { RealizedPositionState, UnrealizedPositionState } from './position.types';
@@ -32,6 +33,18 @@ export declare function computeRealizedPositionState(fills: Fill[]): RealizedPos
  * @returns The realized position state those rows add up to.
  */
 export declare function aggregateRealizedPositionState(assetPnLs: AssetRealizedPnL[]): RealizedPositionState;
+/**
+ * Total the funding attributed to one position, across every asset that earned any.
+ *
+ * Deliberately totals the attribution map rather than the position's legs. Funding
+ * follows exposure, not fills, so an asset that carried exposure without a fill has
+ * funding and no leg. Summing the legs would silently drop it, which is why this total
+ * can exceed the breakdown a caller can see.
+ *
+ * @param fundingByAsset - Funding attributed per asset, as the wire records it.
+ * @returns The position's net funding carry.
+ */
+export declare function sumAttributedFunding(fundingByAsset: PositionTotalFundingPayment): BigNumber;
 /**
  * Weighted-average entry (cost-basis) price per instrument in a position, derived purely from
  * fills — no mark price needed. This is the authoritative source for a position's entry price;

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.8.0",
+  "version": "1.0.0",
   "description": "Pear Protocol Utility functions",
   "private": false,
   "type": "module",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.3.2",
-    "@pear-protocol/types": "^1.31.0",
+    "@pear-protocol/types": "^2.0.0",
     "@scure/base": "^2.3.0",
     "bignumber.js": "9.3.1"
   },