@pear-protocol/utils 1.0.0 → 1.2.0

package/dist/fills/compute.d.ts

@@ -8,5 +8,9 @@ import type { Fill } from './fill.types';
  *  - Reduce position   : entry price unchanged
  *  - Close to zero     : keep last entry price (for tracking purpose)
  *  - Flip sign         : entry price resets to flip fill's price
+ *
+ * A 0-price (unpriceable synthetic) fill that opens or adds to the held size taints the
+ * basis until the size flattens or flips: the entry is then unknown and reported as zero,
+ * the same "no entry" answer callers already get for an empty ledger.
  */
 export declare function computeEntryPriceForAsset(fills: Fill[]): BigNumber;

package/dist/index.d.ts

@@ -10,4 +10,5 @@ export * from './proxy';
 export * from './sync/index';
 export * from './validate-leverage';
 export * from './validate-quantity';
+export * from './vaults/index';
 export * from './xauth/index';

package/dist/index.js

@@ -1,7 +1,8 @@
 import BigNumber7 from 'bignumber.js';
 import { sha256 } from '@noble/hashes/sha2';
-import { bytesToHex, randomBytes, utf8ToBytes } from '@noble/hashes/utils';
+import { bytesToHex, utf8ToBytes, randomBytes } from '@noble/hashes/utils';
 import { WATERMARK_FUTURE_SKEW_MS } from '@pear-protocol/types';
+import { keccak_256 } from '@noble/hashes/sha3';
 import { base64urlnopad } from '@scure/base';
 
 var __defProp = Object.defineProperty;
@@ -124,6 +125,7 @@ __name(compareValue, "compareValue");
 function computeEntryPriceForAsset(fills) {
   let entryPrice = ZERO;
   let positionSize = ZERO;
+  let unpriced = false;
   for (const fill of fills) {
     const price = new BigNumber7(fill.price);
     const quantity = new BigNumber7(fill.quantity);
@@ -133,11 +135,16 @@ function computeEntryPriceForAsset(fills) {
     const isFlip = !positionSize.isZero() && !newPositionSize.isZero() && newPositionSize.isPositive() !== positionSize.isPositive();
     if (positionSize.isZero() || isFlip) {
       entryPrice = price;
+      unpriced = price.isZero();
     } else if (isSameDirection) {
       entryPrice = entryPrice.times(positionSize.abs()).plus(price.times(quantity)).div(newPositionSize.abs());
+      unpriced = unpriced || price.isZero();
     }
     positionSize = newPositionSize;
   }
+  if (unpriced) {
+    return ZERO;
+  }
   return entryPrice;
 }
 __name(computeEntryPriceForAsset, "computeEntryPriceForAsset");
@@ -381,6 +388,9 @@ function computeAssetUnrealizedPnLs(exposureMap, priceMap, fills) {
     const currentPrice = new BigNumber7(priceString);
     const assetFills = fills.filter((fill) => fill.symbol === id);
     const entryPrice = computeEntryPriceForAsset(assetFills);
+    if (entryPrice.isZero()) {
+      continue;
+    }
     const upnl = signedQuantity.multipliedBy(currentPrice.minus(entryPrice));
     result.push({
       id,
@@ -1133,6 +1143,7 @@ function precisePrice(connector, raw, precision, side = "BUY", slippageTolerance
     case "bybit":
     case "okx":
     case "lighter":
+    case "lighter_rhc":
       return preciseTickGridPrice(effectiveRaw, precision, side);
   }
 }
@@ -1197,6 +1208,7 @@ function preciseQuantity(connector, raw, precision, side) {
     case "bybit":
     case "okx":
     case "lighter":
+    case "lighter_rhc":
       return preciseStepGridQuantity(raw, precision, side);
   }
 }
@@ -1266,6 +1278,7 @@ __name(proxyFetch, "proxyFetch");
 
 // src/sync/applicables/constants.ts
 var DUST = parse("0.00000001");
+var LATE_FILL_GRACE_MS = 5 * 6e4;
 var MISSED_HISTORY_FILL_PREFIX = "opening-synthetic-";
 var BASKET_RULES = [
   // V2 Basket Hyperliquid — legs of one Pear basket order share the order's cloid.
@@ -1278,13 +1291,22 @@ function isPearCloid(connector, cloid) {
   if (!cloid) {
     return false;
   }
-  return PEAR_CLOID_CHECK[connector]?.(cloid) ?? false;
+  return PEAR_CLOID_CHECK[connector](cloid);
 }
 __name(isPearCloid, "isPearCloid");
 var PEAR_CLOID_CHECK = {
   hyperliquid: /* @__PURE__ */ __name((cloid) => cloid.startsWith("0x50454152"), "hyperliquid"),
-  lighter: /* @__PURE__ */ __name((cloid) => cloid.length === 15 && cloid.startsWith("10"), "lighter")
+  lighter: isLighterPearCloid,
+  lighter_rhc: isLighterPearCloid,
+  // No Pear brand is minted into a CEX client order id, so provenance cannot be read from it.
+  binance: /* @__PURE__ */ __name(() => false, "binance"),
+  bybit: /* @__PURE__ */ __name(() => false, "bybit"),
+  okx: /* @__PURE__ */ __name(() => false, "okx")
 };
+function isLighterPearCloid(cloid) {
+  return cloid.length === 15 && cloid.startsWith("10");
+}
+__name(isLighterPearCloid, "isLighterPearCloid");
 
 // src/sync/applicables/basket.ts
 var Basket = class _Basket {
@@ -1292,12 +1314,14 @@ var Basket = class _Basket {
     __name(this, "Basket");
   }
   legs;
-  constructor(legs) {
+  fills;
+  constructor(legs, fills) {
     this.legs = legs;
+    this.fills = fills;
   }
   /** Detect baskets from a fill stream, returned in ascending time order. */
   static detect(fills) {
-    return groupFillsIntoBaskets(fills).map((group) => new _Basket(combineFillsBySymbolAndSide(group)));
+    return groupFillsIntoBaskets(fills).map((group) => new _Basket(combineFillsBySymbolAndSide(group), group));
   }
   /** Active long symbol set the matcher compares against open positions. */
   get longs() {
@@ -1504,189 +1528,6 @@ var Exposure = class _Exposure {
   }
 };
 
-// src/sync/applicables/matching.ts
-function matchPositions(args) {
-  const { tradeAccountId, orphanFills, pear } = args;
-  const book = WorkingBook.load({
-    tradeAccountId,
-    openPositions: pear.positions()
-  });
-  for (const basket of Basket.detect(orphanFills)) {
-    const exactCloseTarget = findExactCloseTarget(book.open(), basket.longs, basket.shorts);
-    const leftover = applyCloses({
-      legs: basket.legs,
-      book,
-      exactCloseTarget
-    });
-    if (leftover.length === 0) {
-      continue;
-    }
-    const target = resolveLeftoverTarget({
-      book,
-      leftover
-    });
-    applyLeftover(target, leftover);
-  }
-  return book.toMatched();
-}
-__name(matchPositions, "matchPositions");
-var WorkingBook = class WorkingBook2 {
-  static {
-    __name(this, "WorkingBook");
-  }
-  tradeAccountId;
-  all = [];
-  openByKey = /* @__PURE__ */ new Map();
-  constructor(tradeAccountId) {
-    this.tradeAccountId = tradeAccountId;
-  }
-  /** Seed the book from existing open DB positions (they arrive pre-filtered by connector). */
-  static load(args) {
-    const { tradeAccountId, openPositions } = args;
-    const book = new WorkingBook2(tradeAccountId);
-    for (const p of openPositions) {
-      const position = {
-        // Trust the position's own stored key — never recompute it from exposure.
-        // A partial fill on the original order leaves exposure short of the
-        // symbols the key was hashed from, so a recomputed key would never match.
-        positionKey: p.positionKey,
-        exposure: Exposure.fromRecord(p.exposure),
-        parts: [],
-        closed: false,
-        existingOrigin: p.origin
-      };
-      book.all.push(position);
-      book.openByKey.set(position.positionKey, position);
-    }
-    return book;
-  }
-  /** Deterministic position key for a symbol set under this book's trade account. */
-  keyFor(symbols) {
-    return generateDeterministicPositionKey({
-      tradeAccountId: this.tradeAccountId,
-      symbols
-    });
-  }
-  /** Currently open working positions, in insertion order. */
-  open() {
-    return this.all.filter((position) => !position.closed);
-  }
-  /** Look up an open working position by its positionKey (for dedup on merge). */
-  findOpenByKey(key) {
-    return this.openByKey.get(key);
-  }
-  /** Register a fresh empty working position under `key` and return it. */
-  create(key) {
-    const position = {
-      positionKey: key,
-      exposure: Exposure.empty(),
-      parts: [],
-      closed: false
-    };
-    this.all.push(position);
-    this.openByKey.set(key, position);
-    return position;
-  }
-  /** Flip a position to closed once every leg is within DUST of zero. */
-  markClosedIfFlat(position) {
-    if (position.closed || !position.exposure.isFlat()) {
-      return;
-    }
-    position.exposure.snapToZero();
-    position.closed = true;
-    this.openByKey.delete(position.positionKey);
-  }
-  /** Working positions that received fills become MatchedPosition records; untouched ones are dropped. */
-  toMatched() {
-    return this.all.filter((position) => position.parts.length > 0).map((position) => ({
-      positionKey: position.positionKey,
-      parts: position.parts,
-      closed: position.closed,
-      exposure: position.exposure,
-      existingOrigin: position.existingOrigin
-    }));
-  }
-};
-function findExactCloseTarget(openList, basketLongs, basketShorts) {
-  return openList.find((position) => {
-    const { longs, shorts } = position.exposure.activeLegs();
-    return setEq(longs, basketShorts) && setEq(shorts, basketLongs);
-  });
-}
-__name(findExactCloseTarget, "findExactCloseTarget");
-var setEq = /* @__PURE__ */ __name((a, b) => a.size === b.size && [
-  ...a
-].every((x) => b.has(x)), "setEq");
-function applyCloses(args) {
-  const { legs, book, exactCloseTarget } = args;
-  const openList = book.open();
-  const leftover = [];
-  for (const leg of legs) {
-    let remaining = leg.totalSize;
-    const closeTargetIsLong = sideSign(leg.side) === -1;
-    const holders = openList.filter((position) => {
-      const qty = position.exposure.get(leg.symbol);
-      if (qty.isZero()) {
-        return false;
-      }
-      return closeTargetIsLong ? qty.isPositive() : qty.isNegative();
-    });
-    if (exactCloseTarget) {
-      holders.sort((a, b) => a === exactCloseTarget ? -1 : b === exactCloseTarget ? 1 : 0);
-    }
-    for (const position of holders) {
-      if (isLessThanOrEqual(remaining, ZERO)) {
-        break;
-      }
-      const have = position.exposure.get(leg.symbol).abs();
-      const reduce = min(have, remaining);
-      position.parts.push(...leg.take(reduce));
-      position.exposure.addDelta(leg.symbol, signedBySide(reduce, leg.side));
-      remaining = remaining.minus(reduce);
-      book.markClosedIfFlat(position);
-    }
-    if (isGreaterThanOrEqual(remaining, DUST)) {
-      leftover.push({
-        side: leg.side,
-        qty: remaining,
-        leg
-      });
-    }
-  }
-  return leftover;
-}
-__name(applyCloses, "applyCloses");
-function resolveLeftoverTarget(args) {
-  const { book, leftover } = args;
-  const leftoverLongs = new Set(leftover.filter((entry) => entry.side === "BUY").map((entry) => entry.leg.symbol));
-  const leftoverShorts = new Set(leftover.filter((entry) => entry.side === "SELL").map((entry) => entry.leg.symbol));
-  const target = book.open().find((position) => {
-    const { longs, shorts } = position.exposure.activeLegs();
-    const sameActiveShape = setEq(leftoverLongs, longs) && setEq(leftoverShorts, shorts);
-    const noDormantLegs = position.exposure.symbols().length === longs.size + shorts.size;
-    return sameActiveShape && noDormantLegs;
-  });
-  if (target) {
-    return target;
-  }
-  const symbols = [
-    .../* @__PURE__ */ new Set([
-      ...leftoverLongs,
-      ...leftoverShorts
-    ])
-  ];
-  const positionKey = book.keyFor(symbols);
-  return book.findOpenByKey(positionKey) ?? book.create(positionKey);
-}
-__name(resolveLeftoverTarget, "resolveLeftoverTarget");
-function applyLeftover(target, leftover) {
-  for (const entry of leftover) {
-    target.parts.push(...entry.leg.take(entry.qty));
-    target.exposure.addSigned(entry.leg.symbol, entry.qty.toFixed(), entry.side);
-  }
-}
-__name(applyLeftover, "applyLeftover");
-
 // src/sync/applicables/synthetics.ts
 function isMissedHistoryFill(fill) {
   return fill.exchangeFillId.startsWith(MISSED_HISTORY_FILL_PREFIX);
@@ -1881,7 +1722,8 @@ function assignSyntheticsToPositions(args) {
       const positionKey = existing ? existing.positionKey : keyOf([
         symbol
       ]);
-      target = positions.find((pos) => pos.positionKey === positionKey) ?? created.find((pos) => pos.positionKey === positionKey);
+      const isKeyTarget = /* @__PURE__ */ __name((pos) => pos.positionKey === positionKey && (!existing || pos.existingOrigin !== void 0), "isKeyTarget");
+      target = positions.find(isKeyTarget) ?? created.find(isKeyTarget);
       if (!target) {
         target = existing ? (
           // seed its exposure and origin so folding the synthetic yields the true
@@ -1958,6 +1800,223 @@ function findGapToTarget(args) {
 }
 __name(findGapToTarget, "findGapToTarget");
 
+// src/sync/applicables/matching.ts
+function matchPositions(args) {
+  const { tradeAccountId, orphanFills, pear } = args;
+  const book = WorkingBook.load({
+    tradeAccountId,
+    openPositions: pear.positions()
+  });
+  for (const basket of Basket.detect(orphanFills)) {
+    const at = basketTime(basket);
+    book.foldIntoLive(at);
+    const exactCloseTarget = findExactCloseTarget(book.live(at), basket.longs, basket.shorts);
+    const leftover = applyCloses({
+      legs: basket.legs,
+      book,
+      exactCloseTarget,
+      at
+    });
+    if (leftover.length === 0) {
+      continue;
+    }
+    const target = resolveLeftoverTarget({
+      book,
+      leftover,
+      at
+    });
+    applyLeftover(target, leftover);
+  }
+  book.foldIntoLive(Number.POSITIVE_INFINITY);
+  return book.toMatched();
+}
+__name(matchPositions, "matchPositions");
+function basketTime(basket) {
+  const realTimestamps = basket.fills.filter((fill) => !isMissedHistoryFill(fill)).map((fill) => fill.timestamp);
+  if (realTimestamps.length === 0) {
+    return Number.POSITIVE_INFINITY;
+  }
+  return Math.min(...realTimestamps);
+}
+__name(basketTime, "basketTime");
+var WorkingBook = class WorkingBook2 {
+  static {
+    __name(this, "WorkingBook");
+  }
+  tradeAccountId;
+  all = [];
+  constructor(tradeAccountId) {
+    this.tradeAccountId = tradeAccountId;
+  }
+  /** Seed the book from existing open DB positions (they arrive pre-filtered by connector). */
+  static load(args) {
+    const { tradeAccountId, openPositions } = args;
+    const book = new WorkingBook2(tradeAccountId);
+    for (const p of openPositions) {
+      const position = {
+        // Trust the position's own stored key — never recompute it from exposure.
+        // A partial fill on the original order leaves exposure short of the
+        // symbols the key was hashed from, so a recomputed key would never match.
+        positionKey: p.positionKey,
+        exposure: Exposure.fromRecord(p.exposure),
+        parts: [],
+        closed: false,
+        existingOrigin: p.origin,
+        // A seeded position takes fills from its creation, less the late-arrival grace.
+        liveFrom: Date.parse(p.createdAt) - LATE_FILL_GRACE_MS
+      };
+      book.all.push(position);
+    }
+    return book;
+  }
+  /** Deterministic position key for a symbol set under this book's trade account. */
+  keyFor(symbols) {
+    return generateDeterministicPositionKey({
+      tradeAccountId: this.tradeAccountId,
+      symbols
+    });
+  }
+  /** Working positions open and already existing at basket time `at`, in insertion order. */
+  live(at) {
+    return this.all.filter((position) => !position.closed && position.liveFrom <= at);
+  }
+  /** Look up a position open and existing at `at` by its positionKey (for dedup on merge). */
+  findLiveByKey(key, at) {
+    return this.live(at).find((position) => position.positionKey === key);
+  }
+  /**
+  * Fold every open position opened mid-replay into the open seeded position sharing its
+  * key once that seeded position is live at `at`. The earlier open was still holding
+  * exposure when the seeded position was created, and the server keeps at most one open
+  * row per key. Ownership is ambiguous here — exposure and timestamps cannot prove the
+  * seeded position traded on top of that history — so the fold conservatively keeps
+  * the attribution the matcher gave before #1067.
+  */
+  foldIntoLive(at) {
+    for (const seeded of this.live(at).filter((position) => position.existingOrigin !== void 0)) {
+      const earlier = this.all.filter((position) => position.existingOrigin === void 0 && !position.closed && position.positionKey === seeded.positionKey);
+      for (const position of earlier) {
+        seeded.parts.push(...position.parts);
+        for (const symbol of position.exposure.symbols()) {
+          seeded.exposure.addDelta(symbol, position.exposure.get(symbol));
+        }
+        this.all = this.all.filter((candidate) => candidate !== position);
+      }
+      this.markClosedIfFlat(seeded);
+    }
+  }
+  /** Register a fresh empty working position under `key` and return it. */
+  create(key) {
+    const position = {
+      positionKey: key,
+      exposure: Exposure.empty(),
+      parts: [],
+      closed: false,
+      // Opened by this replay's own fills, so it takes fills from the start.
+      liveFrom: Number.NEGATIVE_INFINITY
+    };
+    this.all.push(position);
+    return position;
+  }
+  /** Flip a position to closed once every leg is within DUST of zero. */
+  markClosedIfFlat(position) {
+    if (position.closed || !position.exposure.isFlat()) {
+      return;
+    }
+    position.exposure.snapToZero();
+    position.closed = true;
+  }
+  /** Working positions that received fills become MatchedPosition records; untouched ones are dropped. */
+  toMatched() {
+    return this.all.filter((position) => position.parts.length > 0).map((position) => ({
+      positionKey: position.positionKey,
+      parts: position.parts,
+      closed: position.closed,
+      exposure: position.exposure,
+      existingOrigin: position.existingOrigin
+    }));
+  }
+};
+function findExactCloseTarget(openList, basketLongs, basketShorts) {
+  return openList.find((position) => {
+    const { longs, shorts } = position.exposure.activeLegs();
+    return setEq(longs, basketShorts) && setEq(shorts, basketLongs);
+  });
+}
+__name(findExactCloseTarget, "findExactCloseTarget");
+var setEq = /* @__PURE__ */ __name((a, b) => a.size === b.size && [
+  ...a
+].every((x) => b.has(x)), "setEq");
+function applyCloses(args) {
+  const { legs, book, exactCloseTarget, at } = args;
+  const openList = book.live(at);
+  const leftover = [];
+  for (const leg of legs) {
+    let remaining = leg.totalSize;
+    const closeTargetIsLong = sideSign(leg.side) === -1;
+    const holders = openList.filter((position) => {
+      const qty = position.exposure.get(leg.symbol);
+      if (qty.isZero()) {
+        return false;
+      }
+      return closeTargetIsLong ? qty.isPositive() : qty.isNegative();
+    });
+    if (exactCloseTarget) {
+      holders.sort((a, b) => a === exactCloseTarget ? -1 : b === exactCloseTarget ? 1 : 0);
+    }
+    for (const position of holders) {
+      if (isLessThanOrEqual(remaining, ZERO)) {
+        break;
+      }
+      const have = position.exposure.get(leg.symbol).abs();
+      const reduce = min(have, remaining);
+      position.parts.push(...leg.take(reduce));
+      position.exposure.addDelta(leg.symbol, signedBySide(reduce, leg.side));
+      remaining = remaining.minus(reduce);
+      book.markClosedIfFlat(position);
+    }
+    if (isGreaterThanOrEqual(remaining, DUST)) {
+      leftover.push({
+        side: leg.side,
+        qty: remaining,
+        leg
+      });
+    }
+  }
+  return leftover;
+}
+__name(applyCloses, "applyCloses");
+function resolveLeftoverTarget(args) {
+  const { book, leftover, at } = args;
+  const leftoverLongs = new Set(leftover.filter((entry) => entry.side === "BUY").map((entry) => entry.leg.symbol));
+  const leftoverShorts = new Set(leftover.filter((entry) => entry.side === "SELL").map((entry) => entry.leg.symbol));
+  const target = book.live(at).find((position) => {
+    const { longs, shorts } = position.exposure.activeLegs();
+    const sameActiveShape = setEq(leftoverLongs, longs) && setEq(leftoverShorts, shorts);
+    const noDormantLegs = position.exposure.symbols().length === longs.size + shorts.size;
+    return sameActiveShape && noDormantLegs;
+  });
+  if (target) {
+    return target;
+  }
+  const symbols = [
+    .../* @__PURE__ */ new Set([
+      ...leftoverLongs,
+      ...leftoverShorts
+    ])
+  ];
+  const positionKey = book.keyFor(symbols);
+  return book.findLiveByKey(positionKey, at) ?? book.create(positionKey);
+}
+__name(resolveLeftoverTarget, "resolveLeftoverTarget");
+function applyLeftover(target, leftover) {
+  for (const entry of leftover) {
+    target.parts.push(...entry.leg.take(entry.qty));
+    target.exposure.addSigned(entry.leg.symbol, entry.qty.toFixed(), entry.side);
+  }
+}
+__name(applyLeftover, "applyLeftover");
+
 // src/sync/applicables/fills.ts
 function assignPartIds(positions) {
   const bySource = /* @__PURE__ */ new Map();
@@ -2618,6 +2677,246 @@ function validateQuantity(quantity, price, precision) {
   return true;
 }
 __name(validateQuantity, "validateQuantity");
+var VAULT_ACTION_DOMAIN = {
+  name: "PearVaultService",
+  version: "1",
+  chainId: 999
+};
+var VAULT_ACTION_TYPES = {
+  "withdraw-to-evm": {
+    WithdrawToEvm: [
+      {
+        name: "vault",
+        type: "address"
+      },
+      {
+        name: "amount",
+        type: "string"
+      },
+      {
+        name: "token",
+        type: "string"
+      },
+      {
+        name: "nonce",
+        type: "string"
+      },
+      {
+        name: "deadline",
+        type: "uint256"
+      }
+    ]
+  },
+  "set-trader": {
+    SetTrader: [
+      {
+        name: "vault",
+        type: "address"
+      },
+      {
+        name: "trader",
+        type: "address"
+      },
+      {
+        name: "nonce",
+        type: "string"
+      },
+      {
+        name: "deadline",
+        type: "uint256"
+      }
+    ]
+  },
+  "agent-approve": {
+    AgentApprove: [
+      {
+        name: "vault",
+        type: "address"
+      },
+      {
+        name: "nonce",
+        type: "string"
+      },
+      {
+        name: "deadline",
+        type: "uint256"
+      }
+    ]
+  },
+  "set-unified-account": {
+    SetUnifiedAccount: [
+      {
+        name: "vault",
+        type: "address"
+      },
+      {
+        name: "nonce",
+        type: "string"
+      },
+      {
+        name: "deadline",
+        type: "uint256"
+      }
+    ]
+  },
+  "update-metadata": {
+    UpdateVaultMetadata: [
+      {
+        name: "vault",
+        type: "address"
+      },
+      {
+        name: "name",
+        type: "string"
+      },
+      {
+        name: "about",
+        type: "string"
+      },
+      {
+        name: "imageUri",
+        type: "string"
+      },
+      {
+        name: "nonce",
+        type: "string"
+      },
+      {
+        name: "deadline",
+        type: "uint256"
+      }
+    ]
+  }
+};
+var CREATE_VAULT_TYPES = {
+  CreateVault: [
+    {
+      name: "leader",
+      type: "address"
+    },
+    {
+      name: "name",
+      type: "string"
+    },
+    {
+      name: "description",
+      type: "string"
+    },
+    {
+      name: "imageUri",
+      type: "string"
+    },
+    {
+      name: "configId",
+      type: "uint256"
+    },
+    {
+      name: "maxWithdrawalPeriodDays",
+      type: "uint256"
+    },
+    {
+      name: "nonce",
+      type: "string"
+    },
+    {
+      name: "deadline",
+      type: "uint256"
+    }
+  ]
+};
+function buildLeaderActionTypedData(action, vaultAddress, body) {
+  const vault = checksumAddress(vaultAddress);
+  const nonce = String(body.nonce ?? "");
+  const deadline = BigInt(body.deadline ?? 0);
+  switch (action) {
+    case "withdraw-to-evm":
+      return {
+        types: VAULT_ACTION_TYPES[action],
+        primaryType: "WithdrawToEvm",
+        message: {
+          vault,
+          amount: String(body.amount ?? ""),
+          token: String(body.tokenId ?? "0"),
+          nonce,
+          deadline
+        }
+      };
+    case "set-trader":
+      return {
+        types: VAULT_ACTION_TYPES[action],
+        primaryType: "SetTrader",
+        message: {
+          vault,
+          trader: checksumAddress(String(body.traderAddress ?? "")),
+          nonce,
+          deadline
+        }
+      };
+    case "agent-approve":
+      return {
+        types: VAULT_ACTION_TYPES[action],
+        primaryType: "AgentApprove",
+        message: {
+          vault,
+          nonce,
+          deadline
+        }
+      };
+    case "set-unified-account":
+      return {
+        types: VAULT_ACTION_TYPES[action],
+        primaryType: "SetUnifiedAccount",
+        message: {
+          vault,
+          nonce,
+          deadline
+        }
+      };
+    case "update-metadata":
+      return {
+        types: VAULT_ACTION_TYPES[action],
+        primaryType: "UpdateVaultMetadata",
+        message: {
+          vault,
+          name: String(body.name ?? ""),
+          about: String(body.about ?? ""),
+          imageUri: String(body.imageUri ?? ""),
+          nonce,
+          deadline
+        }
+      };
+  }
+}
+__name(buildLeaderActionTypedData, "buildLeaderActionTypedData");
+function buildCreateVaultMessage(body) {
+  return {
+    leader: checksumAddress(String(body.leader ?? "")),
+    name: String(body.name ?? ""),
+    description: String(body.description ?? ""),
+    imageUri: String(body.imageUri ?? ""),
+    configId: BigInt(String(body.configId ?? 0)),
+    maxWithdrawalPeriodDays: BigInt(String(body.maxWithdrawalPeriodDays ?? 0)),
+    nonce: String(body.nonce ?? ""),
+    deadline: BigInt(body.deadline ?? 0)
+  };
+}
+__name(buildCreateVaultMessage, "buildCreateVaultMessage");
+function checksumAddress(address) {
+  if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+    throw new Error(`invalid address: ${address}`);
+  }
+  const lower = address.slice(2).toLowerCase();
+  const hash = keccak_256(utf8ToBytes(lower));
+  let out = "";
+  for (const [index, byte] of hash.subarray(0, 20).entries()) {
+    const high = lower.charAt(index * 2);
+    const low = lower.charAt(index * 2 + 1);
+    out += byte >> 4 >= 8 ? high.toUpperCase() : high;
+    out += (byte & 15) >= 8 ? low.toUpperCase() : low;
+  }
+  return `0x${out}`;
+}
+__name(checksumAddress, "checksumAddress");
 var STORAGE_PREFIX = "pear.x-handoff.";
 function startXHandoff(storage) {
   const handoffId = base64urlnopad.encode(randomBytes(16));
@@ -2689,4 +2988,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, 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, 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/sync/applicables/basket.d.ts

@@ -12,6 +12,7 @@ import type { FillPart } from './types';
  */
 export declare class Basket {
     readonly legs: CombinedLeg[];
+    readonly fills: HttpTypes.UnknownExternalFill[];
     private constructor();
     /** Detect baskets from a fill stream, returned in ascending time order. */
     static detect(fills: HttpTypes.UnknownExternalFill[]): Basket[];

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

@@ -9,6 +9,13 @@ import type { BasketRule } from './types';
  * tolerance: a genuine partial close (>= 1e-8) stays open, as it should.
  */
 export declare const DUST: BigNumber;
+/**
+ * How long before an open position's creation a fill may still belong to it. Fills can
+ * reach sync out of order by seconds across cycles (observed up to ~30s), so a strict
+ * cutoff would split one position in two; anything older predates the position and must
+ * not be replayed into it (see pear-protocol/backend#1067).
+ */
+export declare const LATE_FILL_GRACE_MS: number;
 export declare const MISSED_HISTORY_FILL_PREFIX = "opening-synthetic-";
 export declare const BASKET_RULES: BasketRule[];
 /**

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

@@ -9,6 +9,11 @@ import type { MatchedPosition } from './types';
  *   - resolveLeftoverTarget merges into a position whose FULL leg set (active and
  *     dormant) is exactly the leftover's, else opens new (same-shape ADDs consolidate here).
  * The asset SET of a position never grows, so positionKey == key(opening symbols).
+ *
+ * Every phase only sees positions that already existed when the basket happened: a
+ * basket older than an open position's creation (beyond LATE_FILL_GRACE_MS) cannot
+ * close, reduce or merge into it, so a late-fetched earlier lifecycle is not bound to a
+ * position opened after it (pear-protocol/backend#1067).
  */
 export declare function matchPositions(args: {
     tradeAccountId: string;

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

@@ -31,6 +31,11 @@ export type WorkingPosition = {
     closed: boolean;
     /** Origin of the seeded existing position; undefined for positions opened mid-replay. */
     existingOrigin?: HttpTypes.PositionOrigin;
+    /**
+     * Earliest basket time (ms) this position may take fills from: its creation minus the
+     * late-fill grace for a seeded position, -Infinity for one opened mid-replay.
+     */
+    liveFrom: number;
 };
 /** A matched position that received fill slices, ready to become an applicable. */
 export type MatchedPosition = {

package/dist/vaults/action-typed-data.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Every action a leader-signed route may carry. A new route must add its member
+ * here, which forces the typed-data switch below to name it at build time.
+ */
+export type LeaderActionName = 'withdraw-to-evm' | 'set-trader' | 'agent-approve' | 'set-unified-account' | 'update-metadata';
+/**
+ * EIP-712 domain for off-chain vault-service auth. `chainId` is pinned to 999
+ * (HyperEVM) by the shared contract — signing is offline, so there is no chain
+ * switch and this must NOT be read from env. `verifyingContract` is omitted on
+ * purpose: this is service auth, not an on-chain contract call.
+ */
+export declare const VAULT_ACTION_DOMAIN: {
+    readonly name: "PearVaultService";
+    readonly version: "1";
+    readonly chainId: 999;
+};
+/**
+ * EIP-712 types per action — the one copy both signer and verifier import.
+ * One struct per action: every signed parameter is a readable field in the
+ * wallet prompt, and the primary-type name itself discriminates the action,
+ * so structurally identical actions can never replay into each other.
+ */
+export declare const VAULT_ACTION_TYPES: {
+    readonly 'withdraw-to-evm': {
+        readonly WithdrawToEvm: readonly [{
+            readonly name: "vault";
+            readonly type: "address";
+        }, {
+            readonly name: "amount";
+            readonly type: "string";
+        }, {
+            readonly name: "token";
+            readonly type: "string";
+        }, {
+            readonly name: "nonce";
+            readonly type: "string";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    };
+    readonly 'set-trader': {
+        readonly SetTrader: readonly [{
+            readonly name: "vault";
+            readonly type: "address";
+        }, {
+            readonly name: "trader";
+            readonly type: "address";
+        }, {
+            readonly name: "nonce";
+            readonly type: "string";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    };
+    readonly 'agent-approve': {
+        readonly AgentApprove: readonly [{
+            readonly name: "vault";
+            readonly type: "address";
+        }, {
+            readonly name: "nonce";
+            readonly type: "string";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    };
+    readonly 'set-unified-account': {
+        readonly SetUnifiedAccount: readonly [{
+            readonly name: "vault";
+            readonly type: "address";
+        }, {
+            readonly name: "nonce";
+            readonly type: "string";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    };
+    readonly 'update-metadata': {
+        readonly UpdateVaultMetadata: readonly [{
+            readonly name: "vault";
+            readonly type: "address";
+        }, {
+            readonly name: "name";
+            readonly type: "string";
+        }, {
+            readonly name: "about";
+            readonly type: "string";
+        }, {
+            readonly name: "imageUri";
+            readonly type: "string";
+        }, {
+            readonly name: "nonce";
+            readonly type: "string";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    };
+};
+/**
+ * EIP-712 type for a create — the one copy both signer and verifier import.
+ * Every signed parameter is a readable field in the wallet prompt.
+ */
+export declare const CREATE_VAULT_TYPES: {
+    readonly CreateVault: readonly [{
+        readonly name: "leader";
+        readonly type: "address";
+    }, {
+        readonly name: "name";
+        readonly type: "string";
+    }, {
+        readonly name: "description";
+        readonly type: "string";
+    }, {
+        readonly name: "imageUri";
+        readonly type: "string";
+    }, {
+        readonly name: "configId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "maxWithdrawalPeriodDays";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "string";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }];
+};
+/**
+ * One action's complete signable typed data. Widened (non-generic) on purpose:
+ * viem's generic overloads cannot take a union of per-action shapes at one call site.
+ */
+export type LeaderActionTypedData = {
+    types: Record<string, readonly {
+        name: string;
+        type: string;
+    }[]>;
+    primaryType: string;
+    message: {
+        vault: `0x${string}`;
+        amount?: string;
+        token?: string;
+        trader?: `0x${string}`;
+        name?: string;
+        about?: string;
+        imageUri?: string;
+        nonce: string;
+        deadline: bigint;
+    };
+};
+/**
+ * Canonical typed-data reconstruction from the request path + body. Signer and
+ * verifier MUST call this same builder with these same normalized values:
+ *  - vault    = the :vaultAddress path segment (checksummed inside the signed EIP-712 message; storage stays lowercase)
+ *  - amount   = body.amount, verbatim decimal string (withdraw only)
+ *  - token    = body.tokenId ?? '0', verbatim string (withdraw only)
+ *  - trader   = body.traderAddress, checksummed (set-trader only)
+ *  - name / about / imageUri = the full display set, verbatim strings; '' means cleared (update-metadata only)
+ *  - nonce    = body.nonce (client-generated; salts the signature for idempotency)
+ *  - deadline = body.deadline (unix seconds) as uint256
+ */
+export declare function buildLeaderActionTypedData(action: LeaderActionName, vaultAddress: string, body: Record<string, unknown>): LeaderActionTypedData;
+/**
+ * Canonical CreateVault reconstruction from the request body. Signer and verifier
+ * MUST call this same builder; absent optionals sign as '' and 0.
+ */
+export declare function buildCreateVaultMessage(body: Record<string, unknown>): {
+    leader: `0x${string}`;
+    name: string;
+    description: string;
+    imageUri: string;
+    configId: bigint;
+    maxWithdrawalPeriodDays: bigint;
+    nonce: string;
+    deadline: bigint;
+};

package/dist/vaults/index.d.ts

@@ -0,0 +1 @@
+export * from './action-typed-data';

package/package.json

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