@pear-protocol/types 1.30.1 → 1.32.0

package/dist/notification/entities.d.ts

@@ -5,9 +5,10 @@ import { z } from 'zod';
  * execute; `ATTACHED_TRIGGER_DISCARDED` means requested close protection could
  * not be placed after a position opened; the `AUTO_REBALANCE_*` categories cover
  * an auto-rebalance config acting on, or stopping itself over, the position it
- * watches; `TRIGGER_CANCELLED_MIS_SCALED` means the remediation sweep cancelled
- * an unreachable stop loss. Outcome lives here in the category; display details
- * live in the `parameters` payload below.
+ * watches; the `TRIGGER_TWAP_*` categories describe a fired trigger starting,
+ * skipping, failing, or cancelling its TWAP; `TRIGGER_CANCELLED_MIS_SCALED`
+ * means the remediation sweep cancelled an unreachable stop loss. Outcome lives
+ * here in the category; display details live in the `parameters` payload below.
  */
 export declare const NotificationCategory: z.ZodEnum<{
     TAKE_PROFIT_HIT: "TAKE_PROFIT_HIT";
@@ -20,6 +21,10 @@ export declare const NotificationCategory: z.ZodEnum<{
     AUTO_REBALANCE_EXECUTED: "AUTO_REBALANCE_EXECUTED";
     AUTO_REBALANCE_FAILED: "AUTO_REBALANCE_FAILED";
     AUTO_REBALANCE_PAUSED: "AUTO_REBALANCE_PAUSED";
+    TRIGGER_TWAP_STARTED: "TRIGGER_TWAP_STARTED";
+    TRIGGER_TWAP_SKIPPED: "TRIGGER_TWAP_SKIPPED";
+    TRIGGER_TWAP_FAILED: "TRIGGER_TWAP_FAILED";
+    TRIGGER_TWAP_POSITION_CHANGED: "TRIGGER_TWAP_POSITION_CHANGED";
     TRIGGER_CANCELLED_MIS_SCALED: "TRIGGER_CANCELLED_MIS_SCALED";
 }>;
 export type NotificationCategory = z.infer<typeof NotificationCategory>;
@@ -333,6 +338,88 @@ export declare const NotificationParameters: z.ZodDiscriminatedUnion<[z.ZodObjec
         LIVE_BETA: "LIVE_BETA";
     }>;
     type: z.ZodLiteral<"auto_rebalance_paused">;
+}, z.core.$strip>, z.ZodObject<{
+    legs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        symbol: z.ZodString;
+        side: z.ZodEnum<{
+            BUY: "BUY";
+            SELL: "SELL";
+        }>;
+    }, z.core.$strip>>;
+    triggerId: z.ZodUUID;
+    positionId: z.ZodUUID;
+    connector: z.ZodEnum<{
+        hyperliquid: "hyperliquid";
+        binance: "binance";
+        bybit: "bybit";
+        okx: "okx";
+        lighter: "lighter";
+    }>;
+    type: z.ZodLiteral<"trigger_twap_started">;
+    scheduleId: z.ZodUUID;
+}, z.core.$strip>, z.ZodObject<{
+    legs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        symbol: z.ZodString;
+        side: z.ZodEnum<{
+            BUY: "BUY";
+            SELL: "SELL";
+        }>;
+    }, z.core.$strip>>;
+    triggerId: z.ZodUUID;
+    positionId: z.ZodUUID;
+    connector: z.ZodEnum<{
+        hyperliquid: "hyperliquid";
+        binance: "binance";
+        bybit: "bybit";
+        okx: "okx";
+        lighter: "lighter";
+    }>;
+    type: z.ZodLiteral<"trigger_twap_skipped">;
+    reason: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    legs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        symbol: z.ZodString;
+        side: z.ZodEnum<{
+            BUY: "BUY";
+            SELL: "SELL";
+        }>;
+    }, z.core.$strip>>;
+    triggerId: z.ZodUUID;
+    positionId: z.ZodUUID;
+    connector: z.ZodEnum<{
+        hyperliquid: "hyperliquid";
+        binance: "binance";
+        bybit: "bybit";
+        okx: "okx";
+        lighter: "lighter";
+    }>;
+    type: z.ZodLiteral<"trigger_twap_failed">;
+    scheduleId: z.ZodOptional<z.ZodUUID>;
+    reason: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    legs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        symbol: z.ZodString;
+        side: z.ZodEnum<{
+            BUY: "BUY";
+            SELL: "SELL";
+        }>;
+    }, z.core.$strip>>;
+    triggerId: z.ZodUUID;
+    positionId: z.ZodUUID;
+    connector: z.ZodEnum<{
+        hyperliquid: "hyperliquid";
+        binance: "binance";
+        bybit: "bybit";
+        okx: "okx";
+        lighter: "lighter";
+    }>;
+    type: z.ZodLiteral<"trigger_twap_position_changed">;
+    scheduleId: z.ZodUUID;
+    reason: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"trigger_cancelled_mis_scaled">;
     triggerId: z.ZodUUID;
@@ -354,6 +441,10 @@ export declare const Notification: z.ZodObject<{
         AUTO_REBALANCE_EXECUTED: "AUTO_REBALANCE_EXECUTED";
         AUTO_REBALANCE_FAILED: "AUTO_REBALANCE_FAILED";
         AUTO_REBALANCE_PAUSED: "AUTO_REBALANCE_PAUSED";
+        TRIGGER_TWAP_STARTED: "TRIGGER_TWAP_STARTED";
+        TRIGGER_TWAP_SKIPPED: "TRIGGER_TWAP_SKIPPED";
+        TRIGGER_TWAP_FAILED: "TRIGGER_TWAP_FAILED";
+        TRIGGER_TWAP_POSITION_CHANGED: "TRIGGER_TWAP_POSITION_CHANGED";
         TRIGGER_CANCELLED_MIS_SCALED: "TRIGGER_CANCELLED_MIS_SCALED";
     }>;
     parameters: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -648,6 +739,88 @@ export declare const Notification: z.ZodObject<{
             LIVE_BETA: "LIVE_BETA";
         }>;
         type: z.ZodLiteral<"auto_rebalance_paused">;
+    }, z.core.$strip>, z.ZodObject<{
+        legs: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            symbol: z.ZodString;
+            side: z.ZodEnum<{
+                BUY: "BUY";
+                SELL: "SELL";
+            }>;
+        }, z.core.$strip>>;
+        triggerId: z.ZodUUID;
+        positionId: z.ZodUUID;
+        connector: z.ZodEnum<{
+            hyperliquid: "hyperliquid";
+            binance: "binance";
+            bybit: "bybit";
+            okx: "okx";
+            lighter: "lighter";
+        }>;
+        type: z.ZodLiteral<"trigger_twap_started">;
+        scheduleId: z.ZodUUID;
+    }, z.core.$strip>, z.ZodObject<{
+        legs: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            symbol: z.ZodString;
+            side: z.ZodEnum<{
+                BUY: "BUY";
+                SELL: "SELL";
+            }>;
+        }, z.core.$strip>>;
+        triggerId: z.ZodUUID;
+        positionId: z.ZodUUID;
+        connector: z.ZodEnum<{
+            hyperliquid: "hyperliquid";
+            binance: "binance";
+            bybit: "bybit";
+            okx: "okx";
+            lighter: "lighter";
+        }>;
+        type: z.ZodLiteral<"trigger_twap_skipped">;
+        reason: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        legs: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            symbol: z.ZodString;
+            side: z.ZodEnum<{
+                BUY: "BUY";
+                SELL: "SELL";
+            }>;
+        }, z.core.$strip>>;
+        triggerId: z.ZodUUID;
+        positionId: z.ZodUUID;
+        connector: z.ZodEnum<{
+            hyperliquid: "hyperliquid";
+            binance: "binance";
+            bybit: "bybit";
+            okx: "okx";
+            lighter: "lighter";
+        }>;
+        type: z.ZodLiteral<"trigger_twap_failed">;
+        scheduleId: z.ZodOptional<z.ZodUUID>;
+        reason: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        legs: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            symbol: z.ZodString;
+            side: z.ZodEnum<{
+                BUY: "BUY";
+                SELL: "SELL";
+            }>;
+        }, z.core.$strip>>;
+        triggerId: z.ZodUUID;
+        positionId: z.ZodUUID;
+        connector: z.ZodEnum<{
+            hyperliquid: "hyperliquid";
+            binance: "binance";
+            bybit: "bybit";
+            okx: "okx";
+            lighter: "lighter";
+        }>;
+        type: z.ZodLiteral<"trigger_twap_position_changed">;
+        scheduleId: z.ZodUUID;
+        reason: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"trigger_cancelled_mis_scaled">;
         triggerId: z.ZodUUID;

package/dist/notification/entities.js

@@ -14,6 +14,10 @@ const NotificationCategory = z.enum([
   "AUTO_REBALANCE_EXECUTED",
   "AUTO_REBALANCE_FAILED",
   "AUTO_REBALANCE_PAUSED",
+  "TRIGGER_TWAP_STARTED",
+  "TRIGGER_TWAP_SKIPPED",
+  "TRIGGER_TWAP_FAILED",
+  "TRIGGER_TWAP_POSITION_CHANGED",
   "TRIGGER_CANCELLED_MIS_SCALED"
 ]);
 const NotificationMetric = z.enum([
@@ -146,6 +150,29 @@ const TriggerCancelledMisScaledNotificationParameters = z.object({
   storedBps: z.number(),
   readingMarginPct: z.number()
 });
+const TriggerTWAPNotificationAnchor = PositionLegParameters.safeExtend({
+  triggerId: z.uuid(),
+  positionId: z.uuid(),
+  connector: Connector
+});
+const TriggerTWAPStartedNotificationParameters = TriggerTWAPNotificationAnchor.safeExtend({
+  type: z.literal("trigger_twap_started"),
+  scheduleId: z.uuid()
+});
+const TriggerTWAPSkippedNotificationParameters = TriggerTWAPNotificationAnchor.safeExtend({
+  type: z.literal("trigger_twap_skipped"),
+  reason: z.string().min(1).max(255)
+});
+const TriggerTWAPFailedNotificationParameters = TriggerTWAPNotificationAnchor.safeExtend({
+  type: z.literal("trigger_twap_failed"),
+  scheduleId: z.uuid().optional(),
+  reason: z.string().min(1).max(255)
+});
+const TriggerTWAPPositionChangedNotificationParameters = TriggerTWAPNotificationAnchor.safeExtend({
+  type: z.literal("trigger_twap_position_changed"),
+  scheduleId: z.uuid(),
+  reason: z.string().min(1).max(255)
+});
 const NotificationParameters = z.discriminatedUnion("type", [
   TakeProfitNotificationParameters,
   StopLossNotificationParameters,
@@ -155,6 +182,10 @@ const NotificationParameters = z.discriminatedUnion("type", [
   AutoRebalanceExecutedNotificationParameters,
   AutoRebalanceFailedNotificationParameters,
   AutoRebalancePausedNotificationParameters,
+  TriggerTWAPStartedNotificationParameters,
+  TriggerTWAPSkippedNotificationParameters,
+  TriggerTWAPFailedNotificationParameters,
+  TriggerTWAPPositionChangedNotificationParameters,
   TriggerCancelledMisScaledNotificationParameters
 ]);
 const Notification = z.object({

package/dist/notification/responses.d.ts

@@ -13,6 +13,10 @@ export declare const NotificationListResponse: z.ZodObject<{
             AUTO_REBALANCE_EXECUTED: "AUTO_REBALANCE_EXECUTED";
             AUTO_REBALANCE_FAILED: "AUTO_REBALANCE_FAILED";
             AUTO_REBALANCE_PAUSED: "AUTO_REBALANCE_PAUSED";
+            TRIGGER_TWAP_STARTED: "TRIGGER_TWAP_STARTED";
+            TRIGGER_TWAP_SKIPPED: "TRIGGER_TWAP_SKIPPED";
+            TRIGGER_TWAP_FAILED: "TRIGGER_TWAP_FAILED";
+            TRIGGER_TWAP_POSITION_CHANGED: "TRIGGER_TWAP_POSITION_CHANGED";
             TRIGGER_CANCELLED_MIS_SCALED: "TRIGGER_CANCELLED_MIS_SCALED";
         }>;
         parameters: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -307,6 +311,88 @@ export declare const NotificationListResponse: z.ZodObject<{
                 LIVE_BETA: "LIVE_BETA";
             }>;
             type: z.ZodLiteral<"auto_rebalance_paused">;
+        }, z.core.$strip>, z.ZodObject<{
+            legs: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                symbol: z.ZodString;
+                side: z.ZodEnum<{
+                    BUY: "BUY";
+                    SELL: "SELL";
+                }>;
+            }, z.core.$strip>>;
+            triggerId: z.ZodUUID;
+            positionId: z.ZodUUID;
+            connector: z.ZodEnum<{
+                hyperliquid: "hyperliquid";
+                binance: "binance";
+                bybit: "bybit";
+                okx: "okx";
+                lighter: "lighter";
+            }>;
+            type: z.ZodLiteral<"trigger_twap_started">;
+            scheduleId: z.ZodUUID;
+        }, z.core.$strip>, z.ZodObject<{
+            legs: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                symbol: z.ZodString;
+                side: z.ZodEnum<{
+                    BUY: "BUY";
+                    SELL: "SELL";
+                }>;
+            }, z.core.$strip>>;
+            triggerId: z.ZodUUID;
+            positionId: z.ZodUUID;
+            connector: z.ZodEnum<{
+                hyperliquid: "hyperliquid";
+                binance: "binance";
+                bybit: "bybit";
+                okx: "okx";
+                lighter: "lighter";
+            }>;
+            type: z.ZodLiteral<"trigger_twap_skipped">;
+            reason: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            legs: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                symbol: z.ZodString;
+                side: z.ZodEnum<{
+                    BUY: "BUY";
+                    SELL: "SELL";
+                }>;
+            }, z.core.$strip>>;
+            triggerId: z.ZodUUID;
+            positionId: z.ZodUUID;
+            connector: z.ZodEnum<{
+                hyperliquid: "hyperliquid";
+                binance: "binance";
+                bybit: "bybit";
+                okx: "okx";
+                lighter: "lighter";
+            }>;
+            type: z.ZodLiteral<"trigger_twap_failed">;
+            scheduleId: z.ZodOptional<z.ZodUUID>;
+            reason: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            legs: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                symbol: z.ZodString;
+                side: z.ZodEnum<{
+                    BUY: "BUY";
+                    SELL: "SELL";
+                }>;
+            }, z.core.$strip>>;
+            triggerId: z.ZodUUID;
+            positionId: z.ZodUUID;
+            connector: z.ZodEnum<{
+                hyperliquid: "hyperliquid";
+                binance: "binance";
+                bybit: "bybit";
+                okx: "okx";
+                lighter: "lighter";
+            }>;
+            type: z.ZodLiteral<"trigger_twap_position_changed">;
+            scheduleId: z.ZodUUID;
+            reason: z.ZodString;
         }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"trigger_cancelled_mis_scaled">;
             triggerId: z.ZodUUID;

package/dist/schedule/entities.d.ts

@@ -29,6 +29,7 @@ export declare const ScheduleCancelledReason: z.ZodEnum<{
 }>;
 export type ScheduleCancelledReason = z.infer<typeof ScheduleCancelledReason>;
 declare const TWAPOpenLeg: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
     symbol: z.ZodString;
     side: z.ZodEnum<{
         BUY: "BUY";
@@ -192,6 +193,7 @@ export declare const TWAPOpen: z.ZodObject<{
         sizeJitterBps: z.ZodInt;
     }, z.core.$strip>;
     legs: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
         symbol: z.ZodString;
         side: z.ZodEnum<{
             BUY: "BUY";
@@ -360,6 +362,7 @@ export declare const Schedule: z.ZodDiscriminatedUnion<[z.ZodObject<{
         sizeJitterBps: z.ZodInt;
     }, z.core.$strip>;
     legs: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
         symbol: z.ZodString;
         side: z.ZodEnum<{
             BUY: "BUY";

package/dist/schedule/entities.js

@@ -30,6 +30,8 @@ const ScheduleCancelledReason = z.enum([
   "POSITION_REVERSED"
 ]);
 const TWAPOpenLeg = z.object({
+  /** PHASE-1 LEG ID: mirrors `symbol` today; required in phase 3 when `symbol` becomes the ticker. */
+  id: InstrumentId.optional(),
   /**
   * Instrument ID
   */

package/dist/schedule/payloads.d.ts

@@ -10,6 +10,7 @@ export declare const CreateTWAPOpen: z.ZodObject<{
     intent: z.ZodLiteral<"OPEN">;
     executionType: z.ZodLiteral<"MARKET">;
     legs: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
         symbol: z.ZodString;
         side: z.ZodEnum<{
             BUY: "BUY";
@@ -46,6 +47,7 @@ export declare const CreateSchedule: z.ZodDiscriminatedUnion<[z.ZodObject<{
     intent: z.ZodLiteral<"OPEN">;
     executionType: z.ZodLiteral<"MARKET">;
     legs: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
         symbol: z.ZodString;
         side: z.ZodEnum<{
             BUY: "BUY";

package/dist/schedule/payloads.js

@@ -1,31 +1,8 @@
 import { z } from 'zod';
 import { ClientIdCode } from '../common/client-id';
-import { RefineMinimumOneSymbol, RefineUniqueSymbols, RefineWeightingSum } from '../common/refinement';
-import { UnsignedDecimalString, AssetWeight, Side } from '../common/schema';
-import { InstrumentId } from '../instrument';
 import { TWAPRandomization, DEFAULT_TWAP_RANDOMIZATION } from './randomization';
+import { FINAL_TWAP_SLICE_START_HEADROOM_SEC, TWAPSliceIntervalSec, TWAPTargetNotional, TWAPOpenLegs } from './twap-config';
 
-const THIRTY_ONE_DAYS_SEC = 60 * 60 * 24 * 31;
-const MIN_TWAP_WINDOW_SEC = 15;
-const SliceIntervalSec = z.int().min(MIN_TWAP_WINDOW_SEC).max(THIRTY_ONE_DAYS_SEC);
-const TargetNotional = UnsignedDecimalString.refine((value) => /[1-9]/.test(value), {
-  message: "Target notional must be greater than zero"
-});
-const TWAPOpenLeg = z.object({
-  /**
-  * Instrument ID
-  */
-  symbol: InstrumentId,
-  /**
-  * Direction to take
-  */
-  side: Side,
-  /**
-  * Share of the parent target notional allocated to this leg
-  */
-  weight: AssetWeight
-});
-const TWAPOpenLegs = z.array(TWAPOpenLeg).superRefine(RefineMinimumOneSymbol).superRefine(RefineUniqueSymbols).superRefine(RefineWeightingSum);
 const BaseSchedule = z.object({
   /**
    * Start at date
@@ -41,8 +18,8 @@ const BaseSchedule = z.object({
   randomization: TWAPRandomization.optional().default(DEFAULT_TWAP_RANDOMIZATION)
 }).refine((data) => data.startAt && data.endAt && data.startAt < data.endAt, {
   message: "Start at date must be before end at date"
-}).refine((data) => data.endAt.getTime() - data.startAt.getTime() >= MIN_TWAP_WINDOW_SEC * 1e3, {
-  message: `TWAP execution window must be at least ${MIN_TWAP_WINDOW_SEC} seconds`
+}).refine((data) => data.endAt.getTime() - data.startAt.getTime() >= FINAL_TWAP_SLICE_START_HEADROOM_SEC * 1e3, {
+  message: `TWAP execution window must be at least ${FINAL_TWAP_SLICE_START_HEADROOM_SEC} seconds`
 });
 const CreateTWAPOpen = BaseSchedule.safeExtend({
   /**
@@ -64,11 +41,11 @@ const CreateTWAPOpen = BaseSchedule.safeExtend({
   /**
   * Target notional
   */
-  targetNotional: TargetNotional,
+  targetNotional: TWAPTargetNotional,
   /**
   * Slice interval in seconds
   */
-  sliceIntervalSec: SliceIntervalSec,
+  sliceIntervalSec: TWAPSliceIntervalSec,
   /**
   * Attribution route code (client_ids.code)
   */
@@ -94,7 +71,7 @@ const CreateTWAPClose = BaseSchedule.safeExtend({
   /**
   * Slice interval in seconds
   */
-  sliceIntervalSec: SliceIntervalSec,
+  sliceIntervalSec: TWAPSliceIntervalSec,
   /**
   * Attribution route code (client_ids.code)
   */

package/dist/schedule/responses.d.ts

@@ -80,6 +80,7 @@ export declare const ScheduleListResponse: z.ZodObject<{
             sizeJitterBps: z.ZodInt;
         }, z.core.$strip>;
         legs: z.ZodArray<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
             symbol: z.ZodString;
             side: z.ZodEnum<{
                 BUY: "BUY";
@@ -250,6 +251,7 @@ export declare const CreateScheduleResponse: z.ZodObject<{
             sizeJitterBps: z.ZodInt;
         }, z.core.$strip>;
         legs: z.ZodArray<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
             symbol: z.ZodString;
             side: z.ZodEnum<{
                 BUY: "BUY";

package/dist/schedule/twap-config.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+export declare const MAX_TWAP_DURATION_SEC: number;
+export declare const MIN_TWAP_SLICE_INTERVAL_SEC = 15;
+export declare const FINAL_TWAP_SLICE_START_HEADROOM_SEC = 15;
+export declare const TWAPSliceIntervalSec: z.ZodInt;
+export declare const TWAPTargetNotional: z.ZodString;
+export declare const TWAPOpenLeg: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    symbol: z.ZodString;
+    side: z.ZodEnum<{
+        BUY: "BUY";
+        SELL: "SELL";
+    }>;
+    weight: z.ZodNumber;
+}, z.core.$strip>;
+export declare const TWAPOpenLegs: z.ZodArray<z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    symbol: z.ZodString;
+    side: z.ZodEnum<{
+        BUY: "BUY";
+        SELL: "SELL";
+    }>;
+    weight: z.ZodNumber;
+}, z.core.$strip>>;
+export declare const TriggerTWAPOpenLegs: z.ZodTuple<[z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    symbol: z.ZodString;
+    side: z.ZodEnum<{
+        BUY: "BUY";
+        SELL: "SELL";
+    }>;
+    weight: z.ZodNumber;
+}, z.core.$strict>], z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    symbol: z.ZodString;
+    side: z.ZodEnum<{
+        BUY: "BUY";
+        SELL: "SELL";
+    }>;
+    weight: z.ZodNumber;
+}, z.core.$strict>>;

package/dist/schedule/twap-config.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { RefineLegIdMatchesSymbol, RefineMinimumOneSymbol, RefineUniqueSymbols, RefineWeightingSum } from '../common/refinement';
+import { UnsignedDecimalString, AssetWeight, Side } from '../common/schema';
+import { InstrumentId } from '../instrument';
+
+const MAX_TWAP_DURATION_SEC = 60 * 60 * 24 * 31;
+const MIN_TWAP_SLICE_INTERVAL_SEC = 15;
+const FINAL_TWAP_SLICE_START_HEADROOM_SEC = 15;
+const TWAPSliceIntervalSec = z.int().min(MIN_TWAP_SLICE_INTERVAL_SEC).max(MAX_TWAP_DURATION_SEC);
+const TWAPTargetNotional = UnsignedDecimalString.refine((value) => /[1-9]/.test(value), {
+  message: "Target notional must be greater than zero"
+});
+const TWAPOpenLeg = z.object({
+  /** PHASE-1 LEG ID: mirrors `symbol` today; required in phase 3 when `symbol` becomes the ticker. */
+  id: InstrumentId.optional(),
+  /** Instrument ID. */
+  symbol: InstrumentId,
+  /** Direction to take. */
+  side: Side,
+  /** Share of the parent target notional allocated to this leg. */
+  weight: AssetWeight
+}).superRefine(RefineLegIdMatchesSymbol);
+const TWAPOpenLegs = z.array(TWAPOpenLeg).superRefine(RefineMinimumOneSymbol).superRefine(RefineUniqueSymbols).superRefine(RefineWeightingSum);
+const TriggerTWAPOpenLeg = TWAPOpenLeg.strict();
+const TriggerTWAPOpenLegs = z.tuple([
+  TriggerTWAPOpenLeg
+]).rest(TriggerTWAPOpenLeg).superRefine(RefineUniqueSymbols).superRefine(RefineWeightingSum);
+
+export { FINAL_TWAP_SLICE_START_HEADROOM_SEC, MAX_TWAP_DURATION_SEC, MIN_TWAP_SLICE_INTERVAL_SEC, TWAPOpenLeg, TWAPOpenLegs, TWAPSliceIntervalSec, TWAPTargetNotional, TriggerTWAPOpenLegs };

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