@varla/polymarket 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @varla/polymarket
 
+## 2.1.0
+
+### Minor Changes
+
+- 24360c5: Added utility exports for decimal parsing, TWAP calculation, and pricing helpers.
+
+  - Exported new utilities: parseDecimalToBigint, twapFromHistory, probToE8, and collateralPriceFromMarkets,- Added deterministic decimal parsing, TWAP computation, and collateral pricing helpers for market data workflows
+
+### Patch Changes
+
+- af66ffb: No functional changes; package metadata formatting was adjusted.
+
+  - Reformat the package.json files array without altering published contents
+
 ## 2.0.1
 
 ### Patch Changes

package/dist/index.d.ts

@@ -15,5 +15,8 @@ export * from "./clob-ws.js";
 export * from "./clob-errors.js";
 export * from "./data-api-client.js";
 export * from "./pnl.js";
+export { parseDecimalToBigint } from "./utils/decimal.js";
+export { twapFromHistory } from "./utils/twap.js";
+export { probToE8, collateralPriceFromMarkets } from "./utils/pricing.js";
 export * from "./bridge-client.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,mBAAmB,CAAC;AAMlC,cAAc,gBAAgB,CAAC;AAM/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAM9B,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AAMjC,cAAc,sBAAsB,CAAC;AAMrC,cAAc,UAAU,CAAC;AAMzB,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,mBAAmB,CAAC;AAMlC,cAAc,gBAAgB,CAAC;AAM/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAM9B,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AAMjC,cAAc,sBAAsB,CAAC;AAMrC,cAAc,UAAU,CAAC;AAMzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAM1E,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -2840,6 +2840,97 @@ function computePnlSummary(openPositions, closedPositions) {
     openCount: openPositions.length
   };
 }
+// src/utils/decimal.ts
+function parseDecimalToBigint(value, decimals) {
+  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 77) {
+    throw new Error(`invalid decimals=${decimals}`);
+  }
+  const s = value.trim();
+  if (!s)
+    throw new Error("empty decimal string");
+  if (s.includes("e") || s.includes("E")) {
+    throw new Error(`scientific notation not supported: ${value}`);
+  }
+  const neg = s.startsWith("-");
+  const raw = neg ? s.slice(1) : s;
+  const parts = raw.split(".");
+  if (parts.length > 2)
+    throw new Error(`invalid decimal: ${value}`);
+  const whole = parts[0] ?? "0";
+  const frac = parts[1] ?? "";
+  if (!/^\d+$/.test(whole))
+    throw new Error(`invalid decimal: ${value}`);
+  if (frac && !/^\d+$/.test(frac))
+    throw new Error(`invalid decimal: ${value}`);
+  const fracPadded = (frac + "0".repeat(decimals)).slice(0, decimals);
+  const n = BigInt(whole) * 10n ** BigInt(decimals) + (fracPadded ? BigInt(fracPadded) : 0n);
+  return neg ? -n : n;
+}
+// src/utils/twap.ts
+function twapFromHistory(params) {
+  const { history, startTs, endTs } = params;
+  if (endTs <= startTs)
+    return 0;
+  if (!history.length)
+    return 0;
+  const xs = history.filter((x) => Number.isFinite(x.t) && Number.isFinite(x.p)).sort((a, b) => a.t - b.t);
+  if (!xs.length)
+    return 0;
+  let curP = 0;
+  for (let i = xs.length - 1;i >= 0; i--) {
+    const x = xs[i];
+    if (!x)
+      continue;
+    if (x.t <= startTs) {
+      curP = x.p;
+      break;
+    }
+  }
+  if (curP === 0 && xs.length > 0) {
+    const first = xs[0];
+    if (first)
+      curP = first.p;
+  }
+  let weighted = 0;
+  let curT = startTs;
+  for (const pt of xs) {
+    const t = pt.t;
+    if (t <= startTs) {
+      curP = pt.p;
+      continue;
+    }
+    if (t >= endTs)
+      break;
+    const dt = t - curT;
+    if (dt > 0)
+      weighted += curP * dt;
+    curT = t;
+    curP = pt.p;
+  }
+  const tail = endTs - curT;
+  if (tail > 0)
+    weighted += curP * tail;
+  return weighted / (endTs - startTs);
+}
+// src/utils/pricing.ts
+function clamp(x, lo, hi) {
+  return Math.min(Math.max(x, lo), hi);
+}
+function probToE8(p) {
+  const clamped = clamp(p, 0, 1);
+  return BigInt(Math.round(clamped * 1e8));
+}
+function collateralPriceFromMarkets(params) {
+  const bestBid = clamp(params.bestBid, 0, 1);
+  const twap = clamp(params.twap, 0, 1);
+  if (bestBid <= 0 && twap <= 0)
+    return 0;
+  if (bestBid <= 0)
+    return twap;
+  if (twap <= 0)
+    return bestBid;
+  return Math.min(bestBid, twap);
+}
 // src/bridge-client.ts
 function buildQuery3(params) {
   const q = new URLSearchParams;
@@ -2966,6 +3057,7 @@ class BridgeClient {
 }
 export {
   validateOrderParams,
+  twapFromHistory,
   toTokenUnits,
   roundUp,
   roundToTickSize,
@@ -2974,8 +3066,10 @@ export {
   resolveBinaryMarketsByConditionId,
   resolveBinaryMarketFromGammaMarket,
   resetClobClient,
+  probToE8,
   priceValid,
   parseRetryAfter,
+  parseDecimalToBigint,
   isValidPrice,
   isTickSizeSmaller,
   isTerminalStatus,
@@ -3006,6 +3100,7 @@ export {
   computePnlSummary,
   computeOpenPnl,
   computeClosedPnl,
+  collateralPriceFromMarkets,
   classifyHttpStatus,
   classifyError,
   chunk,

package/dist/utils/decimal.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Deterministic decimal string → bigint parsing.
+ *
+ * General-purpose utility for converting human-readable decimal strings
+ * (e.g. CLOB prices "0.51", sizes "1000.123456") into fixed-point bigints
+ * with a specified number of fractional digits.
+ *
+ * No floating-point arithmetic is used — the conversion is purely string-based
+ * to avoid precision loss.
+ *
+ * @example
+ * ```ts
+ * parseDecimalToBigint("0.5", 8)   // 50_000_000n
+ * parseDecimalToBigint("1", 8)     // 100_000_000n
+ * parseDecimalToBigint("100.0", 6) // 100_000_000n
+ * ```
+ */
+export declare function parseDecimalToBigint(value: string, decimals: number): bigint;
+//# sourceMappingURL=decimal.d.ts.map

package/dist/utils/decimal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decimal.d.ts","sourceRoot":"","sources":["../../src/utils/decimal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAuB5E"}

package/dist/utils/pricing.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure pricing utilities for prediction-market collateral valuation.
+ *
+ * These functions convert between probability space [0, 1] and the on-chain
+ * E8 fixed-point representation used by VarlaOracle (1e8 = 100%).
+ */
+/**
+ * Convert a [0, 1] probability to oracle E8 units (1e8 = 100%).
+ *
+ * Clamps input to [0, 1] and rounds to nearest integer.
+ *
+ * @example
+ * ```ts
+ * probToE8(0.5)  // 50_000_000n
+ * probToE8(1.0)  // 100_000_000n
+ * probToE8(0)    // 0n
+ * ```
+ */
+export declare function probToE8(p: number): bigint;
+/**
+ * Conservative lending collateral price for risk management.
+ *
+ * Returns `min(bestBid, twap)` clamped to [0, 1], with fallback logic
+ * when one side is unavailable (zero).
+ *
+ * **Why bestBid?** In a lending protocol, collateral must be valued at the
+ * price it can be liquidated at — the best bid (what buyers will pay NOW).
+ * Using mid or ask enables manipulation via thin ask orders.
+ *
+ * **TWAP smoothing** prevents flash bid spikes from inflating collateral value.
+ *
+ * @example
+ * ```ts
+ * collateralPriceFromMarkets({ bestBid: 0.60, twap: 0.65 }) // 0.60
+ * collateralPriceFromMarkets({ bestBid: 0.70, twap: 0.65 }) // 0.65
+ * collateralPriceFromMarkets({ bestBid: 0, twap: 0.50 })    // 0.50 (fallback)
+ * ```
+ */
+export declare function collateralPriceFromMarkets(params: {
+    bestBid: number;
+    twap: number;
+}): number;
+//# sourceMappingURL=pricing.d.ts.map

package/dist/utils/pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../src/utils/pricing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAG1C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAS5F"}

package/dist/utils/twap.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Time-Weighted Average Price (TWAP) computation.
+ *
+ * Computes TWAP over a `{t, p}[]` history series using step-function semantics:
+ * price `p[i]` is assumed to hold constant until the next data point `p[i+1]`.
+ *
+ * Works with any Polymarket CLOB prices-history response shape.
+ *
+ * @example
+ * ```ts
+ * const history = [
+ *   { t: 1000, p: 0.5 },
+ *   { t: 2000, p: 0.6 },
+ *   { t: 3000, p: 0.55 },
+ * ];
+ * twapFromHistory({ history, startTs: 1000, endTs: 4000 });
+ * // → time-weighted average over the window
+ * ```
+ */
+export declare function twapFromHistory(params: {
+    history: Array<{
+        t: number;
+        p: number;
+    }>;
+    startTs: number;
+    endTs: number;
+}): number;
+//# sourceMappingURL=twap.d.ts.map

package/dist/utils/twap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"twap.d.ts","sourceRoot":"","sources":["../../src/utils/twap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACtC,OAAO,EAAE,KAAK,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CA+CT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@varla/polymarket",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "High-performance Polymarket SDK",
   "type": "module",
   "main": "./dist/index.js",