@pear-protocol/utils 0.4.1 → 0.5.0

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

@@ -7,17 +7,41 @@ export type AssetUnrealizedPnL = {
     currentPrice: BigNumber;
     upnl: BigNumber;
 };
-export type AssetRealization = {
+/**
+ * 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 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';
     fillId: string;
     gross: BigNumber;
+    entryPrice: BigNumber;
+    exitPrice: BigNumber;
+    closedQuantity: BigNumber;
+} | {
+    kind: 'UNPRICED';
+    fillId: string;
+    closedQuantity: BigNumber;
 };
 export type AssetRealizedPnL = {
     id: InstrumentId;
     grossPnl: BigNumber;
     netPnl: BigNumber;
     undeterminedSize: BigNumber;
+    exitQuantity: BigNumber;
+    exitNotional: BigNumber;
+    exitVwap: BigNumber | null;
     totalFees: BigNumber;
     tradeFees: BigNumber;
     pearFees: BigNumber;
-    realizations: AssetRealization[];
+    closures: AssetClosure[];
 };

package/dist/asset/index.d.ts

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

package/dist/basket/derive-basket-key.d.ts

@@ -0,0 +1,11 @@
+import type { InstrumentId } from '@pear-protocol/types';
+/**
+ * The canonical basket key: sha256 hex over the instrument ids a basket holds long
+ * and short, each side sorted, spelled as {"long":[...],"short":[...]}.
+ *
+ * This is the `basketKey` the backend reports on /markets/baskets rows and accepts
+ * in /markets/baskets/positions, derived byte-for-byte the way the backend derives
+ * it (deriveBasketKeyFromParts). The format is FROZEN: persisted rows are stored
+ * under it, so neither the sort, the payload spelling, nor the hash may change.
+ */
+export declare function deriveBasketKey(longInstrumentIds: InstrumentId[], shortInstrumentIds: InstrumentId[]): string;

package/dist/basket/derive-basket-key.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/basket/index.d.ts

@@ -1 +1,2 @@
 export * from './compute';
+export * from './derive-basket-key';

package/dist/index.js

@@ -1,6 +1,7 @@
 import BigNumber9 from 'bignumber.js';
 import { sha256 } from '@noble/hashes/sha256';
 import { bytesToHex } from '@noble/hashes/utils';
+import { WATERMARK_FUTURE_SKEW_MS } from '@pear-protocol/types';
 
 // src/asset/compute.ts
 function parse(value) {
@@ -185,17 +186,21 @@ function computeAssetRealizedPnLs(fills) {
     const tradeFees = assetFills.reduce((acc, fill) => acc.plus(new BigNumber9(fill.tradeFee ?? "0")), ZERO);
     const pearFees = assetFills.reduce((acc, fill) => acc.plus(new BigNumber9(fill.pearFee ?? "0")), ZERO);
     const totalFees = tradeFees.plus(pearFees);
-    const { gross: grossPnl, undeterminedSize, realizations } = walkAssetFills(assetFills);
+    const { gross: grossPnl, undeterminedSize, closures, exitQuantity, exitNotional } = walkAssetFills(assetFills);
     const netPnl = grossPnl.minus(totalFees);
+    const exitVwap = isZero(exitQuantity) ? null : divide(exitNotional, exitQuantity);
     result.push({
       id,
       grossPnl,
       netPnl,
       undeterminedSize,
+      exitQuantity,
+      exitNotional,
+      exitVwap,
       totalFees,
       tradeFees,
       pearFees,
-      realizations
+      closures
     });
   }
   return result;
@@ -206,7 +211,9 @@ function walkAssetFills(fills) {
   let basisUnpriced = false;
   let gross = ZERO;
   let undeterminedSize = ZERO;
-  const realizations = [];
+  const closures = [];
+  let exitQuantity = ZERO;
+  let exitNotional = ZERO;
   for (const fill of fills) {
     const price = parse(fill.price);
     const quantity = parse(fill.quantity);
@@ -216,10 +223,24 @@ function walkAssetFills(fills) {
       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);
-        realizations.push({ fillId: fill.id, 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));
       }
     }
     const isSameDirection = !isZero(positionSize) && isPositive(positionSize) === isPositive(signedQuantity);
@@ -233,7 +254,13 @@ function walkAssetFills(fills) {
     }
     positionSize = newPositionSize;
   }
-  return { gross, undeterminedSize, realizations };
+  return {
+    gross,
+    undeterminedSize,
+    closures,
+    exitQuantity,
+    exitNotional
+  };
 }
 function computeBasketWeightedRatioV1(basket, priceMap) {
   let logSum = 0;
@@ -251,6 +278,13 @@ function computeBasketWeightedRatioV1(basket, priceMap) {
   }
   return exponentiate(logSum);
 }
+function deriveBasketKey(longInstrumentIds, shortInstrumentIds) {
+  const payload = JSON.stringify({
+    long: [...longInstrumentIds].sort((a, b) => a.localeCompare(b)),
+    short: [...shortInstrumentIds].sort((a, b) => a.localeCompare(b))
+  });
+  return bytesToHex(sha256(new TextEncoder().encode(payload)));
+}
 function contractsToBase(contracts, contractSize) {
   return new BigNumber9(contracts).times(contractSize);
 }
@@ -330,7 +364,9 @@ function computeUnrealizedPositionState(exposureMap, priceMap, fills) {
   };
 }
 function computeRealizedPositionState(fills) {
-  const assetPnLs = computeAssetRealizedPnLs(fills);
+  return aggregateRealizedPositionState(computeAssetRealizedPnLs(fills));
+}
+function aggregateRealizedPositionState(assetPnLs) {
   const grossPnl = computePositionGrossRealizedPnL(assetPnLs);
   const netPnl = computePositionNetRealizedPnL(assetPnLs);
   const tradeFees = assetPnLs.reduce((acc, asset) => acc.plus(asset.tradeFees), ZERO);
@@ -1663,7 +1699,10 @@ function _isValidExternalQuantity(quantity) {
   return isGreaterThan(quantity, ZERO);
 }
 function _isValidExternalTimestamp(timestamp) {
-  return Number.isFinite(timestamp) && timestamp >= 0;
+  if (!Number.isFinite(timestamp) || timestamp < 0) {
+    return false;
+  }
+  return timestamp <= Date.now() + WATERMARK_FUTURE_SKEW_MS;
 }
 function groupConfirmablesByPosition(confirmableFills) {
   return confirmableFills.reduce((acc, fill) => {
@@ -1752,4 +1791,4 @@ function validateQuantity(quantity, price, precision) {
   return true;
 }
 
-export { BIPS, ZERO, abs, add, baseToContracts, buildApplicables, compareValue, computeAssetEntryNotional, computeAssetGrossRealizedPnL, computeAssetRealizedPnLs, computeAssetUndeterminedSizes, computeAssetUnrealizedPnL, computeAssetUnrealizedPnLs, computeBasketWeightedRatioV1, computeEntryPriceForAsset, computePositionEntryPrices, computeRealizedPnlBySymbol, computeRealizedPnlFromFills, computeRealizedPositionState, computeSyncPayload, computeUnrealizedPositionState, computeUnrealizedPositionStateFromEntryPrices, configureProxy, contractsToBase, countDecimals, divide, exponentiate, generateDeterministicPositionKey, isEqualTo, isFiniteDecimal, isGreaterThan, isGreaterThanOrEqual, isLessThan, isLessThanOrEqual, isNegative, isPositive, isZero, min, multiply, negate, parse, precisePrice, preciseQuantity, proxyFetch, sideSign, sign, signed, signedBySide, subtract, toDecimalString, validateLeverage, validateQuantity };
+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, generateDeterministicPositionKey, isEqualTo, isFiniteDecimal, isGreaterThan, isGreaterThanOrEqual, isLessThan, isLessThanOrEqual, isNegative, isPositive, isZero, min, multiply, negate, parse, precisePrice, preciseQuantity, proxyFetch, sideSign, sign, signed, signedBySide, subtract, toDecimalString, validateLeverage, validateQuantity };

package/dist/position/compute.d.ts

@@ -1,4 +1,5 @@
 import type { InstrumentId } from '@pear-protocol/types';
+import type { AssetRealizedPnL } from '../asset/asset.types';
 import type { Fill } from '../fills/fill.types';
 import type { RealizedPositionState, UnrealizedPositionState } from './position.types';
 type ExposureMap = Record<InstrumentId, string>;
@@ -19,6 +20,18 @@ export declare function computeUnrealizedPositionState(exposureMap: ExposureMap,
  * @returns The realized position state.
  */
 export declare function computeRealizedPositionState(fills: Fill[]): RealizedPositionState;
+/**
+ * Roll already-walked per-asset rows up into the position total.
+ *
+ * Separated from computeRealizedPositionState so a caller that already holds the
+ * per-asset rows can total them without walking the ledger a second time. The
+ * position total and the per-asset detail then come from one execution of the walk,
+ * which is the guarantee that makes them impossible to disagree.
+ *
+ * @param assetPnLs - Per-asset realized rows from computeAssetRealizedPnLs.
+ * @returns The realized position state those rows add up to.
+ */
+export declare function aggregateRealizedPositionState(assetPnLs: AssetRealizedPnL[]): RealizedPositionState;
 /**
  * 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/sync/compute.d.ts

@@ -1,4 +1,4 @@
-import type { HttpTypes } from '@pear-protocol/types';
+import { type HttpTypes } from '@pear-protocol/types';
 import type { ComputeSyncPayloadArgs, ComputeSyncPayloadResult } from './types';
 /**
  * Derive the full sync payload from raw exchange data and local state.
@@ -29,5 +29,5 @@ export declare function _normalizeCloid(cloid?: string | null): string | undefin
 export declare function _normalizeExchangeFillId(exchangeFillId?: string | null): string | undefined;
 /** Rejects scientific-notation quantities (e.g. 1e-8) that cannot be safely parsed as fills. */
 export declare function _isValidExternalQuantity(quantity: string): boolean;
-/** Returns true only when the timestamp is a non-negative finite number. */
+/** Returns true only when the timestamp is a non-negative finite number no further than clock skew ahead of now. */
 export declare function _isValidExternalTimestamp(timestamp: number): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/utils",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Pear Protocol Utility functions",
   "private": false,
   "type": "module",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.3.2",
-    "@pear-protocol/types": "^1.15.1",
+    "@pear-protocol/types": "^1.17.0",
     "bignumber.js": "9.3.1"
   },
   "devDependencies": {