@pear-protocol/utils 1.2.0 → 1.3.0

package/dist/copy/equity-fraction.d.ts

@@ -0,0 +1,13 @@
+/** Pure gross-notional valuation for copy sizing. */
+import type { Fill, InstrumentPriceMap, PositionExposure, TradeLeg, UnsignedDecimalString } from '@pear-protocol/types';
+/** Size a non-empty set of validated positive fill notionals without a market-price lookup. */
+export declare function computeFilledEntrySizing(fills: ReadonlyArray<Pick<Fill, 'symbol' | 'usd'>>, equity: UnsignedDecimalString): {
+    equityFraction: UnsignedDecimalString;
+    legNotionals: Record<string, UnsignedDecimalString>;
+};
+/** Value signed exposure against equity; missing prices contribute no notional. */
+export declare function computeEquityFraction(exposure: PositionExposure, priceMap: InstrumentPriceMap, equity: UnsignedDecimalString): UnsignedDecimalString;
+/** Value USD and quantity entry legs; missing quantity prices contribute no notional. */
+export declare function computeEntryEquityFraction(legs: ReadonlyArray<Pick<TradeLeg, 'symbol' | 'mode' | 'amount'>>, priceMap: InstrumentPriceMap, equity: UnsignedDecimalString): UnsignedDecimalString;
+/** Divide valued notional by validated positive equity without capping leverage. */
+export declare function computeNotionalEquityFraction(notional: Fill['usd'], equity: UnsignedDecimalString): UnsignedDecimalString;

package/dist/copy/index.d.ts

@@ -0,0 +1 @@
+export * from './equity-fraction';

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './asset/index';
 export * from './basket/index';
 export * from './contract-size';
+export * from './copy/index';
 export * from './fills/index';
 export * from './math/index';
 export * from './position/index';

package/dist/index.js

@@ -875,6 +875,61 @@ function baseToContracts(base, contractSize) {
 }
 __name(baseToContracts, "baseToContracts");
 
+// src/copy/equity-fraction.ts
+function computeFilledEntrySizing(fills, equity) {
+  const notionals = /* @__PURE__ */ new Map();
+  let total = parse("0");
+  for (const fill of fills) {
+    const notional = parse(fill.usd);
+    notionals.set(fill.symbol, (notionals.get(fill.symbol) ?? parse("0")).plus(notional));
+    total = total.plus(notional);
+  }
+  const legNotionals = {};
+  for (const [symbol, notional] of notionals) {
+    legNotionals[symbol] = notional.toFixed();
+  }
+  return {
+    equityFraction: computeNotionalEquityFraction(total.toFixed(), equity),
+    legNotionals
+  };
+}
+__name(computeFilledEntrySizing, "computeFilledEntrySizing");
+function computeEquityFraction(exposure, priceMap, equity) {
+  let notional = parse("0");
+  for (const [symbol, quantity] of Object.entries(exposure)) {
+    const price = priceMap[symbol];
+    if (price !== void 0) {
+      notional = notional.plus(parse(quantity).abs().multipliedBy(price));
+    }
+  }
+  return computeNotionalEquityFraction(notional.toFixed(), equity);
+}
+__name(computeEquityFraction, "computeEquityFraction");
+function computeEntryEquityFraction(legs, priceMap, equity) {
+  let notional = parse("0");
+  for (const leg of legs) {
+    const amount = parse(leg.amount).abs();
+    switch (leg.mode) {
+      case "USD":
+        notional = notional.plus(amount);
+        break;
+      case "QUANTITY": {
+        const price = priceMap[leg.symbol];
+        if (price !== void 0) {
+          notional = notional.plus(amount.multipliedBy(price));
+        }
+        break;
+      }
+    }
+  }
+  return computeNotionalEquityFraction(notional.toFixed(), equity);
+}
+__name(computeEntryEquityFraction, "computeEntryEquityFraction");
+function computeNotionalEquityFraction(notional, equity) {
+  return parse(notional).dividedBy(equity).toFixed();
+}
+__name(computeNotionalEquityFraction, "computeNotionalEquityFraction");
+
 // src/fills/group.ts
 function groupFillsByPosition(fills) {
   const byPosition = /* @__PURE__ */ new Map();
@@ -2055,7 +2110,7 @@ function assignPartIds(positions) {
   };
 }
 __name(assignPartIds, "assignPartIds");
-function partToApplicableFill(part, id, connector) {
+function partToApplicableFill(part, id, connector, liquidationOutcome) {
   const fill = part.source;
   const base = {
     exchangeFillId: id.exchangeFillId,
@@ -2088,7 +2143,10 @@ function partToApplicableFill(part, id, connector) {
     isExternal: !fromPear,
     tradeFee: feeShareForPart(fill.tradeFee, part.quantity, fill.quantity),
     builderFee: feeShareForPart(fill.builderFee, part.quantity, fill.quantity),
-    liquidation: fill.liquidation,
+    liquidation: fill.liquidation ? {
+      mark: fill.liquidation.mark,
+      outcome: liquidationOutcome ?? void 0
+    } : null,
     ...id.original ? {
       original: id.original
     } : {}
@@ -2122,7 +2180,7 @@ function assembleApplicables(args) {
 }
 __name(assembleApplicables, "assembleApplicables");
 function assembleOneApplicable(pos, connector, partIdFor, assignedSynthetics, now) {
-  const realFills = pos.parts.map((part) => partToApplicableFill(part, partIdFor(part), connector)).sort((a, b) => a.timestamp - b.timestamp);
+  const { realFills, closedReason } = finalizeRealFills(pos, connector, partIdFor);
   const syntheticFills = assignedSynthetics.map((synthetic) => buildSyntheticFill({
     positionKey: pos.positionKey,
     connector,
@@ -2146,13 +2204,38 @@ function assembleOneApplicable(pos, connector, partIdFor, assignedSynthetics, no
     origin,
     status,
     ...closed ? {
-      closedReason: "NETTED"
+      closedReason
     } : {},
     fills,
     metadata: buildMetadata(new Set(exposure.symbols()), realFills)
   };
 }
 __name(assembleOneApplicable, "assembleOneApplicable");
+function finalizeRealFills(position, connector, partIdFor) {
+  const newestFirst = [
+    ...position.parts
+  ].sort((a, b) => a.source.timestamp - b.source.timestamp).reverse();
+  const exposure = position.exposure.clone();
+  const realFills = [];
+  let closedReason = "NETTED";
+  for (const [index, part] of newestFirst.entries()) {
+    const after = exposure.get(part.source.symbol);
+    const flatAfter = exposure.isFlat();
+    exposure.addDelta(part.source.symbol, negate(signedBySide(part.quantity, part.source.side)));
+    const reducesLeg = isGreaterThan(exposure.get(part.source.symbol).abs(), after.abs());
+    const liquidationOutcome = part.source.liquidation && reducesLeg ? flatAfter ? "CLOSED" : "REDUCED" : null;
+    if (index === 0 && position.closed && liquidationOutcome === "CLOSED") {
+      closedReason = "LIQUIDATED";
+    }
+    realFills.push(partToApplicableFill(part, partIdFor(part), connector, liquidationOutcome));
+  }
+  realFills.reverse();
+  return {
+    realFills,
+    closedReason
+  };
+}
+__name(finalizeRealFills, "finalizeRealFills");
 function finalExposure(pos, synthetics) {
   const exposure = pos.exposure.clone();
   for (const synthetic of synthetics) {
@@ -2403,8 +2486,7 @@ __name(isStrictTimestampBoundary, "isStrictTimestampBoundary");
 async function computeSyncPayload(args) {
   const { tradeAccountId, connector, openPositions, entryBySymbol, provisionalFills, confirmedExchangeFillIds, externalFills, exchangePositions, neverSynced } = args;
   const fillsToProcess = _prepareExternalFills(externalFills, confirmedExchangeFillIds);
-  const { reconcilables, confirmables: confirmableFills, orphans } = _segregateExternalFills(provisionalFills, fillsToProcess);
-  const confirmablesByPosition = groupConfirmablesByPosition(confirmableFills);
+  const orphans = _excludeClaimedFills(provisionalFills, fillsToProcess);
   const { keptOrphans, firstSyncTrim } = applyFirstSyncCutoff({
     neverSynced,
     fillsToProcess,
@@ -2421,13 +2503,11 @@ async function computeSyncPayload(args) {
     exchangePositions
   });
   const mustPostFirstSyncCheckpoint = neverSynced;
-  if (!mustPostFirstSyncCheckpoint && isEmptyCycle(reconcilables, confirmablesByPosition, applicables)) {
+  if (!mustPostFirstSyncCheckpoint && applicables.length === 0) {
     return null;
   }
   const externalMaxTs = latestFillTimestamp(fillsToProcess);
   return {
-    reconcilables: Object.keys(reconcilables).length > 0 ? reconcilables : null,
-    confirmables: Object.keys(confirmablesByPosition).length > 0 ? confirmablesByPosition : null,
     applicables,
     exchangePositions,
     meta: {
@@ -2469,77 +2549,20 @@ function _prepareExternalFills(externalFills, confirmedExchangeFillIdsInput) {
   return Array.from(dedupedByExchangeFillId.values()).sort((a, b) => a.timestamp - b.timestamp);
 }
 __name(_prepareExternalFills, "_prepareExternalFills");
-function _segregateExternalFills(provisionalFills, externalFills) {
-  const provisionalFillsMap = /* @__PURE__ */ new Map();
+function _excludeClaimedFills(provisionalFills, externalFills) {
+  const ownedCloids = /* @__PURE__ */ new Set();
   for (const fill of provisionalFills) {
     const cloid = _normalizeCloid(fill.cloid);
-    if (!cloid) {
-      continue;
+    if (cloid) {
+      ownedCloids.add(cloid);
     }
-    provisionalFillsMap.set(cloid, fill);
   }
-  const orphans = [];
-  const fillsByCloid = /* @__PURE__ */ new Map();
-  for (const fill of externalFills) {
+  return externalFills.filter((fill) => {
     const cloid = _normalizeCloid(fill.cloid);
-    if (!cloid) {
-      orphans.push(fill);
-    } else {
-      fillsByCloid.set(cloid, [
-        ...fillsByCloid.get(cloid) || [],
-        fill
-      ]);
-    }
-  }
-  const reconcilables = {};
-  const confirmableFills = [];
-  for (const [cloid, fills] of fillsByCloid.entries()) {
-    if (fills.length > 1) {
-      const provisional = provisionalFillsMap.get(cloid);
-      if (provisional) {
-        const [first, second, ...rest] = fills;
-        if (!first || !second) {
-          throw new Error("Corrupted state: sibling group must contain at least 2 fills for reconcile");
-        }
-        reconcilables[cloid] = [
-          {
-            ...first,
-            cloid
-          },
-          {
-            ...second,
-            cloid
-          },
-          ...rest.map((fill) => ({
-            ...fill,
-            cloid
-          }))
-        ];
-      } else {
-        orphans.push(...fills);
-      }
-    } else {
-      const fill = fills[0];
-      const provisional = provisionalFillsMap.get(cloid);
-      if (provisional) {
-        confirmableFills.push({
-          ...fill,
-          type: "confirm",
-          cloid,
-          positionId: provisional.positionId
-        });
-      } else {
-        orphans.push(fill);
-      }
-    }
-  }
-  return {
-    reconcilables,
-    confirmables: confirmableFills,
-    orphans
-  };
+    return cloid === void 0 || !ownedCloids.has(cloid);
+  });
 }
-__name(_segregateExternalFills, "_segregateExternalFills");
+__name(_excludeClaimedFills, "_excludeClaimedFills");
 function _normalizeCloid(cloid) {
   const value = cloid?.trim();
   if (!value) {
@@ -2573,16 +2596,6 @@ function _isValidExternalTimestamp(timestamp) {
   return timestamp <= Date.now() + WATERMARK_FUTURE_SKEW_MS;
 }
 __name(_isValidExternalTimestamp, "_isValidExternalTimestamp");
-function groupConfirmablesByPosition(confirmableFills) {
-  return confirmableFills.reduce((acc, fill) => {
-    acc[fill.positionId] = [
-      ...acc[fill.positionId] || [],
-      fill
-    ];
-    return acc;
-  }, {});
-}
-__name(groupConfirmablesByPosition, "groupConfirmablesByPosition");
 function latestFillTimestamp(fills) {
   const last = fills[fills.length - 1];
   if (!last) {
@@ -2633,10 +2646,6 @@ function applyFirstSyncCutoff(args) {
   };
 }
 __name(applyFirstSyncCutoff, "applyFirstSyncCutoff");
-function isEmptyCycle(reconcilables, confirmablesByPosition, applicables) {
-  return Object.keys(reconcilables).length === 0 && Object.keys(confirmablesByPosition).length === 0 && applicables.length === 0;
-}
-__name(isEmptyCycle, "isEmptyCycle");
 
 // src/validate-leverage.ts
 function validateLeverage(leverage, instrument) {
@@ -2988,4 +2997,4 @@ function takeVerifier(handoffId, storage) {
 }
 __name(takeVerifier, "takeVerifier");
 
-export { BIPS, CREATE_VAULT_TYPES, VAULT_ACTION_DOMAIN, VAULT_ACTION_TYPES, ZERO, abs, add, aggregateRealizedPositionState, baseToContracts, buildApplicables, buildCreateVaultMessage, buildLeaderActionTypedData, 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 };
+export { BIPS, CREATE_VAULT_TYPES, VAULT_ACTION_DOMAIN, VAULT_ACTION_TYPES, ZERO, abs, add, aggregateRealizedPositionState, baseToContracts, buildApplicables, buildCreateVaultMessage, buildLeaderActionTypedData, compareValue, computeAssetEntryNotional, computeAssetGrossRealizedPnL, computeAssetRealizedPnLs, computeAssetUndeterminedSizes, computeAssetUnrealizedPnL, computeAssetUnrealizedPnLs, computeBasketWeightedRatioV1, computeDeployedCapital, computeDeployedCapitalState, computeEntryEquityFraction, computeEntryPriceForAsset, computeEquityFraction, computeFillTransitions, computeFilledEntrySizing, computeMaxBasketSize, computeMultiQuoteBasketSize, computeNotionalEquityFraction, 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/key.d.ts

@@ -11,8 +11,8 @@ type PositionKeyInput = {
  * 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.
+ * SYMBOL-MIGRATION id-forever: `symbols` must be instrument ids
+ * (`leg.id ?? leg.symbol`, or exposure keys). A display ticker here re-hashes and orphans every position.
  */
 export declare function generateDeterministicPositionKey(input: PositionKeyInput): string;
 export {};

package/dist/sync/applicables/fills.d.ts

@@ -13,4 +13,4 @@ export declare function assignPartIds(positions: MatchedPosition[]): (part: Fill
  * missed-history synthetic (external, priced to reconcile with the exchange entry).
  * Fees are quantity-prorated when the source fill was split across positions.
  */
-export declare function partToApplicableFill(part: FillPart, id: PartId, connector: HttpTypes.Connector): HttpTypes.ApplicableFill;
+export declare function partToApplicableFill(part: FillPart, id: PartId, connector: HttpTypes.Connector, liquidationOutcome: 'CLOSED' | 'REDUCED' | null): HttpTypes.ApplicableFill;

package/dist/sync/compute.d.ts

@@ -14,15 +14,10 @@ export declare function computeSyncPayload(args: ComputeSyncPayloadArgs): Promis
  */
 export declare function _prepareExternalFills(externalFills: HttpTypes.UnknownExternalFill[], confirmedExchangeFillIdsInput: string[]): HttpTypes.UnknownExternalFill[];
 /**
- * Partition external fills into reconcilables, confirmables, and orphans.
- * Fills whose cloid matches a provisional fill we own go to confirm or reconcile;
- * everything else (no cloid, or cloid we do not own) becomes an orphan.
+ * Drop external fills whose cloid is claimed by a provisional fill we own.
+ * The server-side syncer owns confirming those fills; the client applies orphans only.
  */
-export declare function _segregateExternalFills(provisionalFills: HttpTypes.ProvisionalFill[], externalFills: HttpTypes.UnknownExternalFill[]): {
-    reconcilables: HttpTypes.ReconcileFillsRequest;
-    confirmables: HttpTypes.ConfirmableExternalFill[];
-    orphans: HttpTypes.UnknownExternalFill[];
-};
+export declare function _excludeClaimedFills(provisionalFills: HttpTypes.ProvisionalFill[], externalFills: HttpTypes.UnknownExternalFill[]): HttpTypes.UnknownExternalFill[];
 /** Trim a cloid; empty or whitespace-only collapses to undefined. */
 export declare function _normalizeCloid(cloid?: string | null): string | undefined;
 /** Normalise an exchange fill id: trim + lowercase; absent or blank → undefined. */

package/dist/sync/types.d.ts

@@ -11,8 +11,6 @@ export type ComputeSyncPayloadArgs = {
     neverSynced: boolean;
 };
 export type ComputeSyncPayloadResult = {
-    reconcilables: HttpTypes.ReconcileFillsRequest | null;
-    confirmables: HttpTypes.ConfirmFillsRequest | null;
     applicables: HttpTypes.ApplicablePosition[];
     exchangePositions: HttpTypes.ExternalPosition[];
     meta: {

package/package.json

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