@symmio/trading-core 0.1.0

package/dist/quotes/grouping/quote-group.d.ts

@@ -0,0 +1,122 @@
+import { Address } from 'viem';
+import { SubAccountIsolationType } from '../../symmio-contracts/account-layer/types';
+import { LockedValues, PositionType } from '../../symmio-contracts/symmio/types';
+import { UnifiedQuote } from '../unified-quote';
+/**
+ * The dimensions a {@link QuoteGroup} is keyed on. Only the fields the active
+ * strategy groups by are set:
+ *
+ * - `MARKET_DIRECTION` → `{ symbolId, positionType }`
+ * - `MARKET` → `{ symbolId }`
+ * - `POSITION` / `CUSTOM` (per-quote) → `{ symbolId, positionType, vaAddress }`
+ *   (the single quote's full identity)
+ *
+ * A custom `keyOf` may set whichever subset it groups on.
+ */
+export interface QuoteGroupBy {
+    /** Market the group covers, when grouped by market. */
+    symbolId?: bigint;
+    /** Trade side the group covers, when grouped by direction. */
+    positionType?: PositionType;
+    /** Virtual Account the group covers, when grouped per single position. */
+    vaAddress?: Address;
+}
+/**
+ * A group's identity: a stable string `key` (for React lists and selection) plus
+ * the structured {@link QuoteGroupBy} dimensions it was keyed on. Returned by a
+ * {@link QuoteGroupKeyFn}.
+ */
+export interface QuoteGroupKey {
+    /** Stable string identity, unique per group within one {@link groupQuotes} call. */
+    key: string;
+    /** The structured dimensions that identify this group. */
+    by: QuoteGroupBy;
+}
+/**
+ * Derives the group a quote belongs to. Built-in strategies provide one per
+ * {@link SubAccountIsolationType}; a consumer supplies their own to group on any
+ * dimension (e.g. by `vaAddress`, or market + direction + VA).
+ *
+ * @param quote - The quote to place into a group.
+ * @returns The group's stable key and structured dimensions.
+ */
+export type QuoteGroupKeyFn = (quote: UnifiedQuote) => QuoteGroupKey;
+/**
+ * How {@link groupQuotes} folds quotes into groups:
+ *
+ * - a {@link SubAccountIsolationType} selects the matching built-in strategy
+ *   (`POSITION` and `CUSTOM` produce one group per quote; `MARKET` groups by
+ *   market; `MARKET_DIRECTION` groups by market + side);
+ * - `{ keyOf }` lets the consumer group on any dimension.
+ *
+ * Reusing the on-chain isolation enum keeps the UI grouping faithful to how the
+ * AccountLayer actually allocates Virtual Accounts for the subaccount.
+ */
+export type QuoteGroupingStrategy = SubAccountIsolationType | {
+    readonly keyOf: QuoteGroupKeyFn;
+};
+/**
+ * Pure, price-independent aggregations over a group's child quotes. Every amount
+ * is 18-decimal wei `bigint`, matching {@link UnifiedQuote}. Metrics that need a
+ * live mark price or VA balance (unrealized PnL, market value, liquidation price)
+ * are intentionally **not** here — they belong to a follow-up slice that injects
+ * those inputs.
+ */
+export interface QuoteGroupMetrics {
+    /** Number of child quotes in the group. */
+    quoteCount: number;
+    /** Children classified as active positions (see `isActivePosition`). */
+    openCount: number;
+    /** Children classified as resting/pending orders (see `isPendingOrder`). */
+    pendingCount: number;
+    /** Σ of each child's original `quantity` (pre-close), wei. */
+    quantity: bigint;
+    /** Σ of each child's open quantity (`quantity − closedAmount`) — the live aggregated size, wei. */
+    openQuantity: bigint;
+    /**
+     * Quantity-weighted average open price across children (wei):
+     * `Σ(openQuantity × price) / Σ openQuantity`, where `price` is `openedPrice`
+     * when known, else `requestedOpenPrice`. `undefined` while the group has no open
+     * size, or while any child still lacks a settled open price (a pending or
+     * optimistic open) — render a loading state in that case.
+     */
+    weightedOpenPrice?: bigint;
+    /** Σ initial notional (`openQuantity × price`) across children, wei. */
+    notional: bigint;
+    /** Σ of each {@link LockedValues} leg (`cva`, `lf`, `partyAmm`, `partyBmm`) across children, wei. */
+    lockedValues: LockedValues;
+    /**
+     * Blended leverage as an 18-decimal fixed-point `bigint` (e.g. `2.5x →
+     * 2_500000000000000000n`): `notional / (Σ cva + lf + partyAmm)`. `undefined`
+     * when the locked partyA margin is `0` (nothing to leverage against).
+     */
+    leverage?: bigint;
+}
+/**
+ * One grouped position: several {@link UnifiedQuote}s in the same market (and,
+ * depending on strategy, the same side) folded into a single row with aggregated
+ * {@link QuoteGroupMetrics}.
+ *
+ * The `quotes`, `by`, and stable `key` are the extension points for later
+ * group-level actions (close-all, nuke, grouped TP/SL): those operate over
+ * `quotes` and identify their target by `key` / `by`.
+ */
+export interface QuoteGroup {
+    /** Stable string identity (React key + selection); unique within one {@link groupQuotes} call. */
+    key: string;
+    /** The dimensions that identify this group. */
+    by: QuoteGroupBy;
+    /**
+     * The Virtual Account this group resolves to, taken from its first on-chain
+     * child (falling back to any child that carries one). `undefined` while the
+     * group is all-optimistic (no on-chain quote has anchored its VA yet).
+     */
+    vaAddress?: Address;
+    /** Child quotes, newest first. */
+    quotes: UnifiedQuote[];
+    /** `true` when more than one quote folds into this group (the single-vs-aggregate render switch). */
+    isAggregate: boolean;
+    /** Pure aggregated metrics over {@link quotes}. */
+    metrics: QuoteGroupMetrics;
+}
+//# sourceMappingURL=quote-group.d.ts.map

package/dist/quotes/grouping/quote-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quote-group.d.ts","sourceRoot":"","sources":["../../../src/quotes/grouping/quote-group.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AAC1F,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACtF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,EAAE,EAAE,YAAY,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,aAAa,CAAC;AAErE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAAG,uBAAuB,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;CAAE,CAAC;AAElG;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,mGAAmG;IACnG,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,YAAY,EAAE,YAAY,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,kGAAkG;IAClG,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,EAAE,EAAE,YAAY,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kCAAkC;IAClC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,qGAAqG;IACrG,WAAW,EAAE,OAAO,CAAC;IACrB,mDAAmD;IACnD,OAAO,EAAE,iBAAiB,CAAC;CAC5B"}

package/dist/quotes/index.d.ts

@@ -0,0 +1,17 @@
+export * from './apply-notification';
+export * from './fees';
+export * from './fingerprint';
+export * from './get-quote-events-by-type';
+export * from './get-quote-funding';
+export * from './get-quote-history';
+export * from './get-sub-account-quotes';
+export * from './grouping';
+export * from './liquidation';
+export * from './open-quantity';
+export * from './reconcile-quotes';
+export * from './resolve-quote-accounts';
+export * from './should-accelerate';
+export * from './to-unified-quote';
+export * from './unified-quote';
+export * from './upnl';
+//# sourceMappingURL=index.d.ts.map

package/dist/quotes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/quotes/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,QAAQ,CAAC"}

package/dist/quotes/liquidation/calculate-liquidation-price.d.ts

@@ -0,0 +1,63 @@
+import { PositionType } from '../../symmio-contracts/symmio/types';
+/**
+ * One open position attributed to an account (sub-account or virtual account).
+ * Used by every aggregate calc that runs over an account's positions (currently
+ * {@link calculateLiquidationPrice}; more to follow).
+ *
+ * Every field is 18-decimal wei `bigint`. `closedAmount` defaults to `0n` when
+ * omitted; `openedPrice` is the settled fill price.
+ */
+export interface AccountPosition {
+    /** Total quote quantity (wei). */
+    quantity: bigint;
+    /** Already-closed quantity (wei). Defaults to `0n`. */
+    closedAmount?: bigint;
+    /** Settled `openedPrice` (wei). */
+    openedPrice: bigint;
+}
+/**
+ * Inputs for {@link calculateLiquidationPrice}. All bigint fields are 18-decimal wei.
+ */
+export interface CalculateLiquidationPriceInputs {
+    /** Active positions in the account (sub-account or virtual account). */
+    positions: readonly AccountPosition[];
+    /** Direction of the account's net position (LONG or SHORT). */
+    positionType: PositionType;
+    /** Account's allocated collateral, from `balanceInfoOfPartyA(account)`. */
+    allocatedBalance: bigint;
+    /** Account's locked CVA, from `balanceInfoOfPartyA(account)`. */
+    lockedCVA: bigint;
+    /** Account's locked LF, from `balanceInfoOfPartyA(account)`. */
+    lockedLF: bigint;
+}
+/**
+ * Liquidation price for an account (sub-account or virtual account), in
+ * 18-decimal-wei collateral units. Aggregates the account's active positions:
+ *
+ * ```
+ * freeBalance   = allocatedBalance − lockedCVA − lockedLF
+ * openQty_i     = quantity_i − closedAmount_i
+ * totalQty      = Σ openQty_i
+ * totalNotional = Σ (openQty_i × openedPrice_i)
+ *
+ * LONG : liqPrice = (totalNotional − freeBalance) / totalQty
+ * SHORT: liqPrice = (totalNotional + freeBalance) / totalQty
+ * ```
+ *
+ * Returns `0n` when `totalQty` is `0n` or the computed price is `≤ 0n`
+ * (typically meaning the account has no liquidation risk at any positive price).
+ * All math is pure `bigint`, so there is no floating-point drift.
+ *
+ * @example
+ * ```ts
+ * const liq = calculateLiquidationPrice({
+ *   positions: [{ quantity: 1_000_000_000_000_000_000n, openedPrice: 2_000_000_000_000_000_000n }],
+ *   positionType: PositionType.LONG,
+ *   allocatedBalance: 200_000_000_000_000_000_000n,
+ *   lockedCVA: 10_000_000_000_000_000_000n,
+ *   lockedLF: 5_000_000_000_000_000_000n,
+ * });
+ * ```
+ */
+export declare function calculateLiquidationPrice(inputs: CalculateLiquidationPriceInputs): bigint;
+//# sourceMappingURL=calculate-liquidation-price.d.ts.map

package/dist/quotes/liquidation/calculate-liquidation-price.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculate-liquidation-price.d.ts","sourceRoot":"","sources":["../../../src/quotes/liquidation/calculate-liquidation-price.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAEnE;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C,wEAAwE;IACxE,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IACtC,+DAA+D;IAC/D,YAAY,EAAE,YAAY,CAAC;IAC3B,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,+BAA+B,GAAG,MAAM,CAiBzF"}

package/dist/quotes/liquidation/calculate-liquidation-price.js

@@ -0,0 +1,17 @@
+import { PositionType as e } from "../../symmio-contracts/symmio/types.js";
+import { WEI as t } from "../../shared/utils/wei.js";
+//#region src/quotes/liquidation/calculate-liquidation-price.ts
+function n(n) {
+	let r = 0n, i = 0n;
+	for (let e of n.positions) {
+		let n = e.quantity - (e.closedAmount ?? 0n);
+		n <= 0n || (r += n, i += n * e.openedPrice / t);
+	}
+	if (r === 0n) return 0n;
+	let a = n.allocatedBalance - n.lockedCVA - n.lockedLF, o = (n.positionType === e.LONG ? i - a : i + a) * t / r;
+	return o > 0n ? o : 0n;
+}
+//#endregion
+export { n as calculateLiquidationPrice };
+
+//# sourceMappingURL=calculate-liquidation-price.js.map

package/dist/quotes/liquidation/calculate-liquidation-price.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculate-liquidation-price.js","names":[],"sources":["../../../src/quotes/liquidation/calculate-liquidation-price.ts"],"sourcesContent":["import { WEI } from \"../../shared/utils/wei\";\nimport { PositionType } from \"../../symmio-contracts/symmio/types\";\n\n/**\n * One open position attributed to an account (sub-account or virtual account).\n * Used by every aggregate calc that runs over an account's positions (currently\n * {@link calculateLiquidationPrice}; more to follow).\n *\n * Every field is 18-decimal wei `bigint`. `closedAmount` defaults to `0n` when\n * omitted; `openedPrice` is the settled fill price.\n */\nexport interface AccountPosition {\n  /** Total quote quantity (wei). */\n  quantity: bigint;\n  /** Already-closed quantity (wei). Defaults to `0n`. */\n  closedAmount?: bigint;\n  /** Settled `openedPrice` (wei). */\n  openedPrice: bigint;\n}\n\n/**\n * Inputs for {@link calculateLiquidationPrice}. All bigint fields are 18-decimal wei.\n */\nexport interface CalculateLiquidationPriceInputs {\n  /** Active positions in the account (sub-account or virtual account). */\n  positions: readonly AccountPosition[];\n  /** Direction of the account's net position (LONG or SHORT). */\n  positionType: PositionType;\n  /** Account's allocated collateral, from `balanceInfoOfPartyA(account)`. */\n  allocatedBalance: bigint;\n  /** Account's locked CVA, from `balanceInfoOfPartyA(account)`. */\n  lockedCVA: bigint;\n  /** Account's locked LF, from `balanceInfoOfPartyA(account)`. */\n  lockedLF: bigint;\n}\n\n/**\n * Liquidation price for an account (sub-account or virtual account), in\n * 18-decimal-wei collateral units. Aggregates the account's active positions:\n *\n * ```\n * freeBalance   = allocatedBalance − lockedCVA − lockedLF\n * openQty_i     = quantity_i − closedAmount_i\n * totalQty      = Σ openQty_i\n * totalNotional = Σ (openQty_i × openedPrice_i)\n *\n * LONG : liqPrice = (totalNotional − freeBalance) / totalQty\n * SHORT: liqPrice = (totalNotional + freeBalance) / totalQty\n * ```\n *\n * Returns `0n` when `totalQty` is `0n` or the computed price is `≤ 0n`\n * (typically meaning the account has no liquidation risk at any positive price).\n * All math is pure `bigint`, so there is no floating-point drift.\n *\n * @example\n * ```ts\n * const liq = calculateLiquidationPrice({\n *   positions: [{ quantity: 1_000_000_000_000_000_000n, openedPrice: 2_000_000_000_000_000_000n }],\n *   positionType: PositionType.LONG,\n *   allocatedBalance: 200_000_000_000_000_000_000n,\n *   lockedCVA: 10_000_000_000_000_000_000n,\n *   lockedLF: 5_000_000_000_000_000_000n,\n * });\n * ```\n */\nexport function calculateLiquidationPrice(inputs: CalculateLiquidationPriceInputs): bigint {\n  let totalQty = 0n;\n  let totalNotional = 0n;\n  for (const position of inputs.positions) {\n    const openQty = position.quantity - (position.closedAmount ?? 0n);\n    if (openQty <= 0n) continue;\n    totalQty += openQty;\n    totalNotional += (openQty * position.openedPrice) / WEI;\n  }\n  if (totalQty === 0n) return 0n;\n\n  const freeBalance = inputs.allocatedBalance - inputs.lockedCVA - inputs.lockedLF;\n  const numerator =\n    inputs.positionType === PositionType.LONG ? totalNotional - freeBalance : totalNotional + freeBalance;\n\n  const liquidationPrice = (numerator * WEI) / totalQty;\n  return liquidationPrice > 0n ? liquidationPrice : 0n;\n}\n"],"mappings":";;;AAiEA,SAAgB,EAA0B,GAAiD;CACzF,IAAI,IAAW,IACX,IAAgB;CACpB,KAAK,IAAM,KAAY,EAAO,WAAW;EACvC,IAAM,IAAU,EAAS,YAAY,EAAS,gBAAgB;EAC1D,KAAW,OACf,KAAY,GACZ,KAAkB,IAAU,EAAS,cAAe;CACtD;CACA,IAAI,MAAa,IAAI,OAAO;CAE5B,IAAM,IAAc,EAAO,mBAAmB,EAAO,YAAY,EAAO,UAIlE,KAFJ,EAAO,iBAAiB,EAAa,OAAO,IAAgB,IAAc,IAAgB,KAEtD,IAAO;CAC7C,OAAO,IAAmB,KAAK,IAAmB;AACpD"}

package/dist/quotes/liquidation/index.d.ts

@@ -0,0 +1,2 @@
+export * from './calculate-liquidation-price';
+//# sourceMappingURL=index.d.ts.map

package/dist/quotes/liquidation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/quotes/liquidation/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC"}

package/dist/quotes/open-quantity.d.ts

@@ -0,0 +1,25 @@
+import { UnifiedQuote } from './unified-quote';
+/**
+ * Compute a quote's remaining **open** size — the live quantity still on the
+ * position, `quantity − closedAmount`.
+ *
+ * A position keeps its original {@link UnifiedQuote.quantity} for its entire life;
+ * a partial close does **not** shrink `quantity`, it accrues into
+ * {@link UnifiedQuote.closedAmount}. The size a trader can still close (and the
+ * figure a UI shows as "position size") is therefore the difference between the
+ * two. When `closedAmount` is absent (an off-chain optimistic open that has not
+ * closed anything yet) it is treated as `0`, so the open size equals `quantity`;
+ * once fully closed `closedAmount === quantity`, so the open size is `0` — the
+ * exact semantics of the on-chain `LibQuote.quoteOpenAmount`.
+ *
+ * @param quote - The amount fields needed to derive the open size.
+ * @returns The remaining open quantity, in 18-decimal wei.
+ *
+ * @example
+ * ```ts
+ * // quantity 142.191812e18, closedAmount 100e18
+ * quoteOpenQuantity(quote); // → 42.191812e18
+ * ```
+ */
+export declare function quoteOpenQuantity(quote: Pick<UnifiedQuote, "quantity" | "closedAmount">): bigint;
+//# sourceMappingURL=open-quantity.d.ts.map

package/dist/quotes/open-quantity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-quantity.d.ts","sourceRoot":"","sources":["../../src/quotes/open-quantity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,GAAG,cAAc,CAAC,GAAG,MAAM,CAEhG"}

package/dist/quotes/open-quantity.js

@@ -0,0 +1,8 @@
+//#region src/quotes/open-quantity.ts
+function e(e) {
+	return e.quantity - (e.closedAmount ?? 0n);
+}
+//#endregion
+export { e as quoteOpenQuantity };
+
+//# sourceMappingURL=open-quantity.js.map

package/dist/quotes/open-quantity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-quantity.js","names":[],"sources":["../../src/quotes/open-quantity.ts"],"sourcesContent":["import type { UnifiedQuote } from \"./unified-quote\";\n\n/**\n * Compute a quote's remaining **open** size — the live quantity still on the\n * position, `quantity − closedAmount`.\n *\n * A position keeps its original {@link UnifiedQuote.quantity} for its entire life;\n * a partial close does **not** shrink `quantity`, it accrues into\n * {@link UnifiedQuote.closedAmount}. The size a trader can still close (and the\n * figure a UI shows as \"position size\") is therefore the difference between the\n * two. When `closedAmount` is absent (an off-chain optimistic open that has not\n * closed anything yet) it is treated as `0`, so the open size equals `quantity`;\n * once fully closed `closedAmount === quantity`, so the open size is `0` — the\n * exact semantics of the on-chain `LibQuote.quoteOpenAmount`.\n *\n * @param quote - The amount fields needed to derive the open size.\n * @returns The remaining open quantity, in 18-decimal wei.\n *\n * @example\n * ```ts\n * // quantity 142.191812e18, closedAmount 100e18\n * quoteOpenQuantity(quote); // → 42.191812e18\n * ```\n */\nexport function quoteOpenQuantity(quote: Pick<UnifiedQuote, \"quantity\" | \"closedAmount\">): bigint {\n  return quote.quantity - (quote.closedAmount ?? 0n);\n}\n"],"mappings":";AAwBA,SAAgB,EAAkB,GAAgE;CAChG,OAAO,EAAM,YAAY,EAAM,gBAAgB;AACjD"}

package/dist/quotes/reconcile-quotes.d.ts

@@ -0,0 +1,101 @@
+import { Address } from 'viem';
+import { PendingInstantClose } from '../solvers/instant-close/get-instant-closes/to-pending-instant-close';
+import { PendingInstantOpen } from '../solvers/instant-open/get-instant-opens/to-pending-instant-open';
+import { Quote } from '../symmio-contracts/symmio/types';
+import { Notification } from '../websocket/notifications/types';
+import { UnifiedQuote } from './unified-quote';
+/**
+ * Inputs to {@link reconcileQuotes}: one snapshot of every quote source. The
+ * result is "active quotes only" — a quote appears in the output iff it is
+ * present in at least one of these sources this tick.
+ */
+export interface ReconcileQuotesInput {
+    /** Sub-account (partyA) the snapshot belongs to. */
+    partyA: Address;
+    /** On-chain open positions (`getPartyAOpenPositions`). */
+    onchainPositions: readonly Quote[];
+    /** On-chain pending quotes hydrated via `getQuote`. */
+    onchainPendingQuotes: readonly Quote[];
+    /** Pending instant-open records from the hedger. */
+    instantOpens: readonly PendingInstantOpen[];
+    /** Pending instant-close records from the hedger. */
+    instantCloses: readonly PendingInstantClose[];
+    /**
+     * Map from a pending instant-open's `tempQuoteId` to the Virtual Account (VA)
+     * address its position will land in (from `resolveQuoteAccounts`). When a temp
+     * id is present here, the optimistic row is stamped with its eventual VA so the
+     * UI can show the VA before the trade anchors on-chain.
+     */
+    instantOpenVaByTempId?: Record<number, Address>;
+    /** Notifications to apply after the merge, in arrival order. */
+    notifications?: readonly Notification[];
+    /**
+     * Rows that anchored on-chain on a prior tick (a notification set their
+     * `quoteId`) but whose on-chain struct has not been read yet — the
+     * `pendingAnchors` returned by the previous {@link reconcileQuotes} call. The
+     * consumer feeds them back so an anchored row survives the gap between "the
+     * hedger drops the pending open" and "the on-chain read returns the quote"
+     * instead of vanishing for a tick. Each is dropped automatically once the
+     * matching on-chain read arrives (its `key` is already populated with the real
+     * struct, so the retained copy is ignored).
+     */
+    retainedAnchors?: readonly UnifiedQuote[];
+}
+/** Output of {@link reconcileQuotes}: the merged rows plus the temp ↔ on-chain links. */
+export interface ReconcileQuotesResult {
+    /** Merged, de-duplicated, lifecycle-tagged rows, newest first. */
+    quotes: UnifiedQuote[];
+    /**
+     * Map from `tempQuoteId` to the on-chain row `key` it resolved to, recorded
+     * **only once the row has anchored on-chain** (`quoteId` present). A
+     * still-optimistic temp id is absent until then, so consumers can use this to
+     * clear an optimistic seed exactly when its on-chain twin exists.
+     */
+    links: Record<number, string>;
+    /**
+     * Rows currently in {@link QuoteLifecycle.WRITE_ONCHAIN} — anchored per a
+     * notification but not yet returned by the on-chain read. The consumer retains
+     * these and feeds them back as {@link ReconcileQuotesInput.retainedAnchors} on
+     * the next tick so they do not flicker out while the RPC catches up.
+     */
+    pendingAnchors: UnifiedQuote[];
+}
+/**
+ * Merge every quote source for a sub-account into one stable, de-duplicated,
+ * lifecycle-tagged list — **active quotes only**: a quote appears iff it is in at
+ * least one source this tick, so a quote that has left every source is simply
+ * absent (no lingering "removed" rows). **Pure** and stateless: given the same
+ * `input` it always returns the same result, reading no clock and no randomness.
+ *
+ * Pipeline:
+ *
+ * 1. On-chain positions + pending quotes become anchored rows; `retainedAnchors`
+ *    re-seed any anchored-but-not-yet-read row so it does not flicker out.
+ * 2. Pending instant-closes overlay the matching on-chain row — `CLOSING` once the
+ *    on-chain status shows the close pending, else `WRITE_ONCHAIN_CLOSE`.
+ * 3. Pending instant-opens become `OPTIMISTIC` rows, **dropped** when an on-chain
+ *    row already carries the same {@link fingerprintQuote} (the trade landed).
+ * 4. Notifications are applied in order to link temp ↔ on-chain ids and advance
+ *    lifecycles (an anchored-but-unread row sits at `WRITE_ONCHAIN`); `collapseByKey`
+ *    then merges a rekeyed optimistic row into its on-chain twin, so the off-chain
+ *    row drops once on-chain.
+ * 5. Rows are sorted by `statusModifyTimestamp` descending (newest first), and the
+ *    `WRITE_ONCHAIN` rows are returned as `pendingAnchors` for the next tick.
+ *
+ * @param input - One snapshot of all sources.
+ * @returns The merged rows plus the temp ↔ on-chain `links`.
+ *
+ * @example
+ * ```ts
+ * const { quotes } = reconcileQuotes({
+ *   partyA,
+ *   onchainPositions,
+ *   onchainPendingQuotes,
+ *   instantOpens,
+ *   instantCloses,
+ *   notifications,
+ * });
+ * ```
+ */
+export declare function reconcileQuotes(input: ReconcileQuotesInput): ReconcileQuotesResult;
+//# sourceMappingURL=reconcile-quotes.d.ts.map

package/dist/quotes/reconcile-quotes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile-quotes.d.ts","sourceRoot":"","sources":["../../src/quotes/reconcile-quotes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sEAAsE,CAAC;AAChH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mEAAmE,CAAC;AAC5G,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kCAAkC,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAIrE,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,MAAM,EAAE,OAAO,CAAC;IAChB,0DAA0D;IAC1D,gBAAgB,EAAE,SAAS,KAAK,EAAE,CAAC;IACnC,uDAAuD;IACvD,oBAAoB,EAAE,SAAS,KAAK,EAAE,CAAC;IACvC,oDAAoD;IACpD,YAAY,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC5C,qDAAqD;IACrD,aAAa,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC9C;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,gEAAgE;IAChE,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED,yFAAyF;AACzF,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,cAAc,EAAE,YAAY,EAAE,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,qBAAqB,CA6ElF"}

package/dist/quotes/reconcile-quotes.js

@@ -0,0 +1,92 @@
+import { QuoteLifecycle as e } from "./unified-quote.js";
+import { applyNotificationToQuotes as t } from "./apply-notification.js";
+import { fingerprintQuote as n } from "./fingerprint.js";
+import { toUnifiedQuoteFromInstantOpen as r, toUnifiedQuoteFromOnchain as i } from "./to-unified-quote.js";
+//#region src/quotes/reconcile-quotes.ts
+function a(a) {
+	let c = /* @__PURE__ */ new Map();
+	for (let e of a.onchainPositions) {
+		let t = l(i(e), a.partyA);
+		c.set(t.key, t);
+	}
+	for (let e of a.onchainPendingQuotes) {
+		let t = l(i(e), a.partyA);
+		c.has(t.key) || c.set(t.key, t);
+	}
+	for (let e of a.retainedAnchors ?? []) c.has(e.key) || c.set(e.key, e);
+	for (let e of a.instantCloses) {
+		let t = `onchain:${e.quoteId}`, n = c.get(t);
+		n && c.set(t, {
+			...n,
+			lifecycle: o(n),
+			quantityToClose: e.quantityToClose,
+			raw: {
+				...n.raw,
+				instantClose: e
+			}
+		});
+	}
+	let d = /* @__PURE__ */ new Set();
+	for (let e of c.values()) e.origin === "onchain" && d.add(n(e));
+	for (let e of a.instantOpens) {
+		let t = r(e);
+		if (d.has(n(t))) continue;
+		let i = a.instantOpenVaByTempId?.[e.tempQuoteId];
+		i && (t.vaAddress = i), c.has(t.key) || c.set(t.key, t);
+	}
+	let f = [...c.values()];
+	for (let e of a.notifications ?? []) f = t(f, e);
+	f = s(f), f.sort((e, t) => {
+		let n = e.statusModifyTimestamp ?? 0n, r = t.statusModifyTimestamp ?? 0n;
+		if (n !== r) return n > r ? -1 : 1;
+		let i = u(e), a = u(t);
+		return i === a ? 0 : i > a ? -1 : 1;
+	});
+	let p = {};
+	for (let e of f) e.tempQuoteId !== void 0 && e.quoteId !== void 0 && (p[e.tempQuoteId] = e.key);
+	let m = f.filter((t) => t.lifecycle === e.WRITE_ONCHAIN);
+	return {
+		quotes: f,
+		links: p,
+		pendingAnchors: m
+	};
+}
+function o(t) {
+	return t.lifecycle === e.CLOSED ? e.CLOSED : t.lifecycle === e.CLOSING ? e.CLOSING : e.OPTIMISTIC_CLOSE;
+}
+function s(e) {
+	let t = /* @__PURE__ */ new Map();
+	for (let n of e) {
+		let e = t.get(n.key);
+		t.set(n.key, e ? c(e, n) : n);
+	}
+	return [...t.values()];
+}
+function c(e, t) {
+	let n = e.raw.onchain ? e : t, r = n === e ? t : e;
+	return {
+		...n,
+		tempQuoteId: n.tempQuoteId ?? r.tempQuoteId,
+		vaAddress: n.vaAddress ?? r.vaAddress,
+		openedPrice: n.openedPrice ?? r.openedPrice,
+		avgClosedPrice: n.avgClosedPrice ?? r.avgClosedPrice,
+		quantityToClose: n.quantityToClose ?? r.quantityToClose,
+		raw: {
+			...r.raw,
+			...n.raw
+		}
+	};
+}
+function l(e, t) {
+	return e.partyA.toLowerCase() === t.toLowerCase() ? e : {
+		...e,
+		vaAddress: e.partyA
+	};
+}
+function u(e) {
+	return e.quoteId === void 0 ? e.tempQuoteId === void 0 ? 0n : BigInt(e.tempQuoteId) : e.quoteId;
+}
+//#endregion
+export { a as reconcileQuotes };
+
+//# sourceMappingURL=reconcile-quotes.js.map

package/dist/quotes/reconcile-quotes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile-quotes.js","names":[],"sources":["../../src/quotes/reconcile-quotes.ts"],"sourcesContent":["import type { Address } from \"viem\";\nimport type { PendingInstantClose } from \"../solvers/instant-close/get-instant-closes/to-pending-instant-close\";\nimport type { PendingInstantOpen } from \"../solvers/instant-open/get-instant-opens/to-pending-instant-open\";\nimport type { Quote } from \"../symmio-contracts/symmio/types\";\nimport type { Notification } from \"../websocket/notifications/types\";\nimport { applyNotificationToQuotes } from \"./apply-notification\";\nimport { fingerprintQuote } from \"./fingerprint\";\nimport { toUnifiedQuoteFromInstantOpen, toUnifiedQuoteFromOnchain } from \"./to-unified-quote\";\nimport { QuoteLifecycle, type UnifiedQuote } from \"./unified-quote\";\n\n/**\n * Inputs to {@link reconcileQuotes}: one snapshot of every quote source. The\n * result is \"active quotes only\" — a quote appears in the output iff it is\n * present in at least one of these sources this tick.\n */\nexport interface ReconcileQuotesInput {\n  /** Sub-account (partyA) the snapshot belongs to. */\n  partyA: Address;\n  /** On-chain open positions (`getPartyAOpenPositions`). */\n  onchainPositions: readonly Quote[];\n  /** On-chain pending quotes hydrated via `getQuote`. */\n  onchainPendingQuotes: readonly Quote[];\n  /** Pending instant-open records from the hedger. */\n  instantOpens: readonly PendingInstantOpen[];\n  /** Pending instant-close records from the hedger. */\n  instantCloses: readonly PendingInstantClose[];\n  /**\n   * Map from a pending instant-open's `tempQuoteId` to the Virtual Account (VA)\n   * address its position will land in (from `resolveQuoteAccounts`). When a temp\n   * id is present here, the optimistic row is stamped with its eventual VA so the\n   * UI can show the VA before the trade anchors on-chain.\n   */\n  instantOpenVaByTempId?: Record<number, Address>;\n  /** Notifications to apply after the merge, in arrival order. */\n  notifications?: readonly Notification[];\n  /**\n   * Rows that anchored on-chain on a prior tick (a notification set their\n   * `quoteId`) but whose on-chain struct has not been read yet — the\n   * `pendingAnchors` returned by the previous {@link reconcileQuotes} call. The\n   * consumer feeds them back so an anchored row survives the gap between \"the\n   * hedger drops the pending open\" and \"the on-chain read returns the quote\"\n   * instead of vanishing for a tick. Each is dropped automatically once the\n   * matching on-chain read arrives (its `key` is already populated with the real\n   * struct, so the retained copy is ignored).\n   */\n  retainedAnchors?: readonly UnifiedQuote[];\n}\n\n/** Output of {@link reconcileQuotes}: the merged rows plus the temp ↔ on-chain links. */\nexport interface ReconcileQuotesResult {\n  /** Merged, de-duplicated, lifecycle-tagged rows, newest first. */\n  quotes: UnifiedQuote[];\n  /**\n   * Map from `tempQuoteId` to the on-chain row `key` it resolved to, recorded\n   * **only once the row has anchored on-chain** (`quoteId` present). A\n   * still-optimistic temp id is absent until then, so consumers can use this to\n   * clear an optimistic seed exactly when its on-chain twin exists.\n   */\n  links: Record<number, string>;\n  /**\n   * Rows currently in {@link QuoteLifecycle.WRITE_ONCHAIN} — anchored per a\n   * notification but not yet returned by the on-chain read. The consumer retains\n   * these and feeds them back as {@link ReconcileQuotesInput.retainedAnchors} on\n   * the next tick so they do not flicker out while the RPC catches up.\n   */\n  pendingAnchors: UnifiedQuote[];\n}\n\n/**\n * Merge every quote source for a sub-account into one stable, de-duplicated,\n * lifecycle-tagged list — **active quotes only**: a quote appears iff it is in at\n * least one source this tick, so a quote that has left every source is simply\n * absent (no lingering \"removed\" rows). **Pure** and stateless: given the same\n * `input` it always returns the same result, reading no clock and no randomness.\n *\n * Pipeline:\n *\n * 1. On-chain positions + pending quotes become anchored rows; `retainedAnchors`\n *    re-seed any anchored-but-not-yet-read row so it does not flicker out.\n * 2. Pending instant-closes overlay the matching on-chain row — `CLOSING` once the\n *    on-chain status shows the close pending, else `WRITE_ONCHAIN_CLOSE`.\n * 3. Pending instant-opens become `OPTIMISTIC` rows, **dropped** when an on-chain\n *    row already carries the same {@link fingerprintQuote} (the trade landed).\n * 4. Notifications are applied in order to link temp ↔ on-chain ids and advance\n *    lifecycles (an anchored-but-unread row sits at `WRITE_ONCHAIN`); `collapseByKey`\n *    then merges a rekeyed optimistic row into its on-chain twin, so the off-chain\n *    row drops once on-chain.\n * 5. Rows are sorted by `statusModifyTimestamp` descending (newest first), and the\n *    `WRITE_ONCHAIN` rows are returned as `pendingAnchors` for the next tick.\n *\n * @param input - One snapshot of all sources.\n * @returns The merged rows plus the temp ↔ on-chain `links`.\n *\n * @example\n * ```ts\n * const { quotes } = reconcileQuotes({\n *   partyA,\n *   onchainPositions,\n *   onchainPendingQuotes,\n *   instantOpens,\n *   instantCloses,\n *   notifications,\n * });\n * ```\n */\nexport function reconcileQuotes(input: ReconcileQuotesInput): ReconcileQuotesResult {\n  const byKey = new Map<string, UnifiedQuote>();\n\n  for (const quote of input.onchainPositions) {\n    const row = withVaAddress(toUnifiedQuoteFromOnchain(quote), input.partyA);\n    byKey.set(row.key, row);\n  }\n  for (const quote of input.onchainPendingQuotes) {\n    const row = withVaAddress(toUnifiedQuoteFromOnchain(quote), input.partyA);\n    if (!byKey.has(row.key)) byKey.set(row.key, row);\n  }\n  /**\n   * Re-seed rows that anchored on a prior tick but have no on-chain struct yet, so\n   * they survive the hedger-drop → on-chain-read gap. Skipped the moment the real\n   * on-chain read populates the same `key` (inserted above), so retention ends\n   * itself once the RPC confirms.\n   */\n  for (const anchor of input.retainedAnchors ?? []) {\n    if (!byKey.has(anchor.key)) byKey.set(anchor.key, anchor);\n  }\n  for (const close of input.instantCloses) {\n    const key = `onchain:${close.quoteId}`;\n    const existing = byKey.get(key);\n    /**\n     * An instant-close always references a quote that already exists on-chain, so\n     * we only overlay the close onto its matching row. If the on-chain row has not\n     * loaded yet we skip it rather than synthesize a placeholder with no market or\n     * side; the overlay applies on the next tick once the position read catches up.\n     */\n    if (!existing) continue;\n    byKey.set(key, {\n      ...existing,\n      lifecycle: overlayCloseLifecycle(existing),\n      quantityToClose: close.quantityToClose,\n      raw: { ...existing.raw, instantClose: close },\n    });\n  }\n\n  const onchainFingerprints = new Set<string>();\n\n  for (const row of byKey.values()) {\n    if (row.origin === \"onchain\") onchainFingerprints.add(fingerprintQuote(row));\n  }\n  for (const open of input.instantOpens) {\n    const row = toUnifiedQuoteFromInstantOpen(open);\n    if (onchainFingerprints.has(fingerprintQuote(row))) continue;\n    const vaAddress = input.instantOpenVaByTempId?.[open.tempQuoteId];\n    if (vaAddress) row.vaAddress = vaAddress;\n    if (!byKey.has(row.key)) byKey.set(row.key, row);\n  }\n  let merged = [...byKey.values()];\n  for (const notification of input.notifications ?? []) {\n    merged = applyNotificationToQuotes(merged, notification);\n  }\n  merged = collapseByKey(merged);\n  merged.sort((a, b) => {\n    const aTs = a.statusModifyTimestamp ?? 0n;\n    const bTs = b.statusModifyTimestamp ?? 0n;\n    if (aTs !== bTs) return aTs > bTs ? -1 : 1;\n    const aId = stableSortKey(a);\n    const bId = stableSortKey(b);\n    if (aId !== bId) return aId > bId ? -1 : 1;\n    return 0;\n  });\n  const links: Record<number, string> = {};\n  for (const row of merged) {\n    /**\n     * Only record a temp ↔ on-chain link once the row has actually anchored\n     * (`quoteId` set). A still-optimistic row carries only its own `temp:` key —\n     * recording that as a \"link\" would let the consumer clear its optimistic seed\n     * before the on-chain twin exists, dropping the row for a tick (the\n     * appear→disappear→reappear flicker).\n     */\n    if (row.tempQuoteId !== undefined && row.quoteId !== undefined) links[row.tempQuoteId] = row.key;\n  }\n  const pendingAnchors = merged.filter((row) => row.lifecycle === QuoteLifecycle.WRITE_ONCHAIN);\n  return { quotes: merged, links, pendingAnchors };\n}\n\n/**\n * Lifecycle for an on-chain row that a pending instant-close overlays. Keep a\n * terminal `CLOSED` as-is; keep `CLOSING` when the on-chain status already shows\n * the close pending; otherwise the close is in-flight but the read still shows the\n * position open — surface {@link QuoteLifecycle.OPTIMISTIC_CLOSE} as the base close\n * stage. Close notifications (applied after this overlay) then advance it to\n * `CLOSE_PRICE_FILLED` → `WRITE_ONCHAIN_CLOSE`; the poll moves it to `CLOSING` once\n * the on-chain status reflects the pending close.\n */\nfunction overlayCloseLifecycle(existing: UnifiedQuote): QuoteLifecycle {\n  if (existing.lifecycle === QuoteLifecycle.CLOSED) return QuoteLifecycle.CLOSED;\n  if (existing.lifecycle === QuoteLifecycle.CLOSING) return QuoteLifecycle.CLOSING;\n  return QuoteLifecycle.OPTIMISTIC_CLOSE;\n}\n\n/**\n * Collapse rows that ended up sharing a `key` after a notification rekeyed an\n * optimistic row (`temp:<id>` → `onchain:<id>`) onto an on-chain twin the poll\n * already returned. Without this the same quote can appear twice — once from the\n * poll and once from the rekeyed optimistic row — yielding duplicate React keys.\n * The genuine on-chain row (the one carrying `raw.onchain`) wins; the optimistic\n * row's `tempQuoteId` / `raw.instantOpen` are grafted on so the temp ↔ on-chain\n * link survives and the optimistic entry can be cleared.\n */\nfunction collapseByKey(rows: UnifiedQuote[]): UnifiedQuote[] {\n  const byKey = new Map<string, UnifiedQuote>();\n  for (const row of rows) {\n    const existing = byKey.get(row.key);\n    byKey.set(row.key, existing ? mergeDuplicateRows(existing, row) : row);\n  }\n  return [...byKey.values()];\n}\n\n/**\n * Merge two rows that resolved to the same `key`, preferring the one that carries\n * the polled on-chain struct and grafting the off-chain identifiers from the other.\n */\nfunction mergeDuplicateRows(a: UnifiedQuote, b: UnifiedQuote): UnifiedQuote {\n  const primary = a.raw.onchain ? a : b;\n  const secondary = primary === a ? b : a;\n  return {\n    ...primary,\n    tempQuoteId: primary.tempQuoteId ?? secondary.tempQuoteId,\n    vaAddress: primary.vaAddress ?? secondary.vaAddress,\n    openedPrice: primary.openedPrice ?? secondary.openedPrice,\n    avgClosedPrice: primary.avgClosedPrice ?? secondary.avgClosedPrice,\n    quantityToClose: primary.quantityToClose ?? secondary.quantityToClose,\n    raw: { ...secondary.raw, ...primary.raw },\n  };\n}\n\n/**\n * Stamp the row's Virtual Account on `vaAddress` when it was read from a VA — in\n * lowcap a VA-scoped position's `partyA` IS its VA, so when the row's `partyA`\n * differs from the sub-account being reconciled we surface it on the dedicated\n * `vaAddress` field for the consumer.\n */\nfunction withVaAddress(row: UnifiedQuote, subAccount: Address): UnifiedQuote {\n  if (row.partyA.toLowerCase() === subAccount.toLowerCase()) return row;\n  return { ...row, vaAddress: row.partyA };\n}\n\n/**\n * Deterministic tiebreak key for rows that share a `statusModifyTimestamp`: the\n * on-chain quote id when anchored, else the (negative) temp id. Keeps the sort\n * order reproducible regardless of the unstable on-chain read order — the\n * contract stores positions with swap-and-pop, so the raw read order reshuffles\n * on every open/close.\n */\nfunction stableSortKey(quote: UnifiedQuote): bigint {\n  if (quote.quoteId !== undefined) return quote.quoteId;\n  if (quote.tempQuoteId !== undefined) return BigInt(quote.tempQuoteId);\n  return 0n;\n}\n"],"mappings":"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"}

package/dist/quotes/resolve-quote-accounts.d.ts

@@ -0,0 +1,74 @@
+import { Address } from 'viem';
+import { Config } from '../core/config';
+import { ChainIdParameter, Compute } from '../shared/types/properties';
+import { PendingInstantOpen } from '../solvers/instant-open/get-instant-opens/to-pending-instant-open';
+/**
+ * Parameters for {@link resolveQuoteAccounts}.
+ */
+export type ResolveQuoteAccountsParameters = Compute<ChainIdParameter & {
+    /** The subaccount whose full quote picture is being assembled. */
+    subAccount: Address;
+    /**
+     * Pending instant-opens for the subaccount. Each lands in a Virtual Account
+     * (VA) that may not exist on-chain yet; its address is predicted up front.
+     */
+    instantOpens?: readonly PendingInstantOpen[];
+    /**
+     * Union the subaccount's existing on-chain VAs into the result.
+     * @default true
+     */
+    includeVirtualAccounts?: boolean;
+    /** Extra accounts to union in (e.g. VAs already known to the consumer). */
+    extraAccounts?: readonly Address[];
+}>;
+/** Result of {@link resolveQuoteAccounts}. */
+export interface ResolveQuoteAccountsResult {
+    /**
+     * The deduplicated, checksummed set of on-chain `partyA` accounts to read
+     * quotes across — the subaccount itself, its existing VAs, the predicted VAs
+     * of its pending instant-opens, and any `extraAccounts`. Order is preserved
+     * (subaccount first, then VAs, then predicted VAs, then extras).
+     */
+    accounts: Address[];
+    /**
+     * Map from a pending instant-open's `tempQuoteId` to the predicted VA address
+     * its position will land in. Lets the caller stamp the optimistic quote row
+     * with its eventual VA before the trade anchors on-chain.
+     */
+    instantOpenVaByTempId: Record<number, Address>;
+}
+/**
+ * Resolve the full set of on-chain `partyA` accounts that together hold a
+ * subaccount's quote picture.
+ *
+ * In lowcap, each isolated position lives under a Virtual Account (VA), and the
+ * VA — not the subaccount — is the on-chain `partyA` for quote reads. A
+ * brand-new instant-open lands in a VA that does not exist on-chain yet, so its
+ * address is predicted from `(subAccount, isolationType, symbolId)` via
+ * {@link getPredictedNextVirtualAccount}. This assembles:
+ *
+ * 1. the subaccount itself;
+ * 2. its existing VAs (when `includeVirtualAccounts`, default `true`);
+ * 3. one predicted VA per pending instant-open (predictions are deduped by
+ *    `(isolationType, symbolId)` and run in parallel);
+ * 4. any `extraAccounts`.
+ *
+ * Addresses are deduped case-insensitively, returned checksummed, and kept in
+ * the order above.
+ *
+ * @param config - The SDK config.
+ * @param parameters - Subaccount, optional pending opens / VA inclusion / extras, optional chain id.
+ * @returns The account set plus the `tempQuoteId` → predicted-VA map.
+ * @throws {SymmError} when the chain is not supported.
+ * @throws Viem's `ContractFunctionExecutionError` and friends for on-chain failures.
+ *
+ * @example
+ * ```ts
+ * const { accounts, instantOpenVaByTempId } = await resolveQuoteAccounts(config, {
+ *   subAccount: "0xsub…",
+ *   instantOpens,
+ * });
+ * ```
+ */
+export declare function resolveQuoteAccounts(config: Config, parameters: ResolveQuoteAccountsParameters): Promise<ResolveQuoteAccountsResult>;
+//# sourceMappingURL=resolve-quote-accounts.d.ts.map

package/dist/quotes/resolve-quote-accounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-quote-accounts.d.ts","sourceRoot":"","sources":["../../src/quotes/resolve-quote-accounts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mEAAmE,CAAC;AAK5G;;GAEG;AACH,MAAM,MAAM,8BAA8B,GAAG,OAAO,CAClD,gBAAgB,GAAG;IACjB,kEAAkE;IAClE,UAAU,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC7C;;;OAGG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,2EAA2E;IAC3E,aAAa,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CACpC,CACF,CAAC;AAEF,8CAA8C;AAC9C,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB;;;;OAIG;IACH,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,8BAA8B,GACzC,OAAO,CAAC,0BAA0B,CAAC,CAwDrC"}