@pear-protocol/types 1.30.1 → 1.31.0

package/dist/statistics/entities.js

@@ -28,15 +28,28 @@ const LeaderboardRow = z.object({
   pearFee: z.string(),
   tradeFee: z.string(),
   totalTrades: z.number(),
-  // The plain average of this account's per-position returns, as a ratio: "0.25" is +25%.
-  // Every position is weighted equally, so a small winner counts as much as a large one —
-  // this is a measure of the trader's decisions, not of the dollars those decisions moved.
+  // This account's return over the window, as a ratio: "0.25" is +25%. The measured
+  // positions' PnL divided by the capital that earned it, so each position weighs by the
+  // money it put at risk — a measure of how the account's dollars did, not of how its
+  // individual calls went.
   //
-  // One formula on every position: (realized + unrealized - fees paid) over the size it
-  // opened with. A closed position holds nothing, so its unrealized half is zero and this
-  // reduces to what the trader kept; a partly reduced open position counts both the profit
-  // it banked and the worth of what it still holds. Only fees of fills that happened are
-  // charged, so a running position never pays for the exit it has not made.
+  // One formula on every position: (realized + unrealized - fees paid) over the most cash that
+  // position had committed at one time. A closed position holds nothing, so its unrealized half
+  // is zero and this reduces to what the trader kept; a partly reduced open position counts
+  // both the profit it banked and the worth of what it still holds. Only fees of fills that
+  // happened are charged, so a running position never pays for the exit it has not made.
+  //
+  // The denominator is cash committed, not market value: each opening fill adds what it paid,
+  // each closing fill releases the share of that commitment the quantity it closed was holding,
+  // and the peak of that running total is what the return is measured against. So it is not the
+  // size the position opened at — a position scaled up afterwards is measured against what it
+  // went on to risk — and not the sum of everything it ever opened either, since capital
+  // reduced and recommitted counts once rather than twice.
+  //
+  // Measuring cash rather than market value is deliberate. A market-value denominator can fall
+  // below the money actually put in when a position is averaged down, which inflates the
+  // return; and no historical price series is kept, so market value could only ever be sampled
+  // at the fills themselves.
   //
   // Measured only where the window holds both the position's open and the moment the
   // measurement is taken at: now for a running position, the closing fill for a finished
@@ -46,8 +59,8 @@ const LeaderboardRow = z.object({
   // Absent when the board could measure none of the account's positions — never "0", which
   // would claim a break-even trader. An account reaches the board with nothing measurable
   // when its only trading in the window closed positions opened before it, when a closed
-  // window left its open positions unpriced, when every position it opened in the window
-  // closed after it, or when a position recorded no opening size.
+  // window left its open positions unpriced, or when every position it opened in the window
+  // closed after it.
   roi: z.string().optional(),
   // The trader's linked X account, published to every caller — the board names its traders
   // on the open internet, signed in or not. Absent for an account whose owner has connected

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/types",
-  "version": "1.30.1",
+  "version": "1.31.0",
   "description": "Pear Protocol Types definitions",
   "private": false,
   "type": "module",