@catalyst-team/poly-sdk 0.4.3 → 0.4.6

package/dist/src/services/order-manager.js

@@ -0,0 +1,853 @@
+/**
+ * OrderManager - Unified Order Creation and Monitoring
+ *
+ * Core Design Philosophy:
+ * - Unifies order creation + lifecycle monitoring in one component
+ * - Encapsulates all Polymarket-specific details (USDC.e, tick size, tokenId, CTF, Polygon)
+ * - Provides complete lifecycle events (CLOB match → tx submit → on-chain confirm)
+ * - Auto-validates orders before submission (market state, balance, precision)
+ * - Auto-watches orders after creation
+ *
+ * ============================================================================
+ * ORDER TYPES AND LIFECYCLE
+ * ============================================================================
+ *
+ * Polymarket supports 4 order types, each with different lifecycle patterns:
+ *
+ * ┌─────────────────────────────────────────────────────────────────────────┐
+ * │ LIMIT ORDERS (createOrder)                                             │
+ * ├─────────────────────────────────────────────────────────────────────────┤
+ * │                                                                         │
+ * │ GTC (Good Till Cancelled) - Default limit order                        │
+ * │ ─────────────────────────────────────────────────────────────────────── │
+ * │ Lifecycle: PENDING → OPEN → PARTIALLY_FILLED* → FILLED or CANCELLED    │
+ * │ Duration:  seconds → minutes → hours → days (until filled/cancelled)   │
+ * │                                                                         │
+ * │   ┌─────────┐    placed     ┌──────┐   partial    ┌──────────────────┐ │
+ * │   │ PENDING │ ───────────→ │ OPEN │ ──────────→ │ PARTIALLY_FILLED │ │
+ * │   └─────────┘              └──────┘             └──────────────────┘ │
+ * │        │                       │                        │            │
+ * │        │ reject                │ cancel                 │ fill/cancel│
+ * │        ↓                       ↓                        ↓            │
+ * │   ┌──────────┐           ┌───────────┐            ┌────────┐        │
+ * │   │ REJECTED │           │ CANCELLED │            │ FILLED │        │
+ * │   └──────────┘           └───────────┘            └────────┘        │
+ * │                                                                       │
+ * │ GTD (Good Till Date) - Limit order with expiration                   │
+ * │ ─────────────────────────────────────────────────────────────────────  │
+ * │ Lifecycle: Same as GTC, but auto-expires at specified time           │
+ * │ Duration:  seconds → specified expiration time                        │
+ * │ Additional terminal state: EXPIRED (when expiration time reached)    │
+ * │                                                                         │
+ * ├─────────────────────────────────────────────────────────────────────────┤
+ * │ MARKET ORDERS (createMarketOrder)                                      │
+ * ├─────────────────────────────────────────────────────────────────────────┤
+ * │                                                                         │
+ * │ FOK (Fill Or Kill) - Must fill completely or cancel immediately       │
+ * │ ───────────────────────────────────────────────────────────────────────│
+ * │ Lifecycle: PENDING → FILLED (success) or PENDING → CANCELLED (fail)   │
+ * │ Duration:  milliseconds (instant execution)                           │
+ * │ Key: NO partial fills - all or nothing                                │
+ * │                                                                         │
+ * │   ┌─────────┐    full fill    ┌────────┐                              │
+ * │   │ PENDING │ ─────────────→ │ FILLED │                              │
+ * │   └─────────┘                └────────┘                              │
+ * │        │                                                               │
+ * │        │ cannot fill completely                                        │
+ * │        ↓                                                               │
+ * │   ┌───────────┐                                                        │
+ * │   │ CANCELLED │  (filledSize = 0)                                     │
+ * │   └───────────┘                                                        │
+ * │                                                                         │
+ * │ FAK (Fill And Kill) - Fill what's available, cancel the rest          │
+ * │ ───────────────────────────────────────────────────────────────────────│
+ * │ Lifecycle: PENDING → FILLED or PENDING → CANCELLED (with partial fill)│
+ * │ Duration:  milliseconds (instant execution)                           │
+ * │ Key: May have partial fills, remainder is cancelled immediately       │
+ * │                                                                         │
+ * │   ┌─────────┐    full fill    ┌────────┐                              │
+ * │   │ PENDING │ ─────────────→ │ FILLED │                              │
+ * │   └─────────┘                └────────┘                              │
+ * │        │                                                               │
+ * │        │ partial fill + cancel rest                                    │
+ * │        ↓                                                               │
+ * │   ┌───────────┐                                                        │
+ * │   │ CANCELLED │  (filledSize > 0, cancelledSize > 0)                  │
+ * │   └───────────┘                                                        │
+ * │                                                                         │
+ * └─────────────────────────────────────────────────────────────────────────┘
+ *
+ * ============================================================================
+ * WHY ORDERMANAGER SUPPORTS ALL ORDER TYPES
+ * ============================================================================
+ *
+ * The key insight is that despite different lifecycles, all order types share
+ * the same underlying status model and event stream:
+ *
+ * 1. UNIFIED STATUS MODEL
+ *    All orders use the same OrderStatus enum: PENDING, OPEN, PARTIALLY_FILLED,
+ *    FILLED, CANCELLED, EXPIRED. The difference is which transitions are valid
+ *    and how quickly they occur.
+ *
+ * 2. SAME WEBSOCKET/POLLING EVENTS
+ *    RealtimeServiceV2's `clob_user` topic emits the same USER_ORDER and
+ *    USER_TRADE events for all order types. The eventType field indicates:
+ *    - PLACEMENT: Order entered the system
+ *    - UPDATE: Order was modified (fill, partial fill)
+ *    - CANCELLATION: Order was cancelled
+ *
+ * 3. STATUS TRANSITION VALIDATION
+ *    The isValidStatusTransition() function handles all valid paths:
+ *    - GTC/GTD: PENDING → OPEN → PARTIALLY_FILLED → FILLED/CANCELLED
+ *    - FOK: PENDING → FILLED or PENDING → CANCELLED (no PARTIALLY_FILLED)
+ *    - FAK: PENDING → FILLED or PENDING → CANCELLED (filledSize may be > 0)
+ *
+ * 4. TERMINAL STATE HANDLING
+ *    All order types eventually reach a terminal state (FILLED, CANCELLED,
+ *    EXPIRED). OrderManager auto-unwatches orders when they reach terminal
+ *    states, regardless of order type.
+ *
+ * 5. FILL EVENT DETECTION
+ *    Whether fills come rapidly (FOK/FAK) or slowly (GTC/GTD), the same
+ *    fill detection logic works: compare filledSize changes and emit
+ *    order_partially_filled or order_filled events.
+ *
+ * Key differences in behavior:
+ * ┌─────────────┬─────────────────────────────────────────────────────────┐
+ * │ Order Type  │ Behavior                                                │
+ * ├─────────────┼─────────────────────────────────────────────────────────┤
+ * │ GTC/GTD     │ May emit many events over long time (hours/days)       │
+ * │             │ watchOrder() monitors until filled/cancelled/expired    │
+ * ├─────────────┼─────────────────────────────────────────────────────────┤
+ * │ FOK/FAK     │ Emit 1-2 events almost instantly (milliseconds)        │
+ * │             │ watchOrder() monitors briefly, auto-unwatches quickly   │
+ * └─────────────┴─────────────────────────────────────────────────────────┘
+ *
+ * ============================================================================
+ * PLATFORM-SPECIFIC IMPLEMENTATION
+ * ============================================================================
+ *
+ * This is a Polymarket-specific implementation. The design allows future extraction
+ * to interfaces if supporting multiple prediction markets, but for now we focus on
+ * clean encapsulation with Polymarket details in private methods.
+ *
+ * @example
+ * ```typescript
+ * const orderMgr = new OrderManager({
+ *   privateKey: '0x...',
+ *   rateLimiter,
+ *   cache,
+ * });
+ *
+ * await orderMgr.start();
+ *
+ * // Listen to complete lifecycle
+ * orderMgr.on('order_opened', (order) => {
+ *   console.log('Order live in orderbook');
+ * });
+ *
+ * orderMgr.on('order_filled', (event) => {
+ *   console.log(`Filled: ${event.fill.size} @ ${event.fill.price}`);
+ * });
+ *
+ * orderMgr.on('transaction_confirmed', (event) => {
+ *   console.log(`On-chain settled: ${event.transactionHash}`);
+ * });
+ *
+ * // Create limit order (GTC by default)
+ * const limitResult = await orderMgr.createOrder({
+ *   tokenId: '0x...',
+ *   side: 'BUY',
+ *   price: 0.52,
+ *   size: 100,
+ * });
+ *
+ * // Create market order (FOK - fill completely or cancel)
+ * const fokResult = await orderMgr.createMarketOrder({
+ *   tokenId: '0x...',
+ *   side: 'BUY',
+ *   amount: 50, // $50 USDC
+ *   orderType: 'FOK',
+ * });
+ *
+ * // Create market order (FAK - fill what's available)
+ * const fakResult = await orderMgr.createMarketOrder({
+ *   tokenId: '0x...',
+ *   side: 'BUY',
+ *   amount: 50,
+ *   orderType: 'FAK',
+ * });
+ * ```
+ */
+import { EventEmitter } from 'events';
+import { ethers } from 'ethers';
+import { TradingService } from './trading-service.js';
+import { RateLimiter } from '../core/rate-limiter.js';
+import { createUnifiedCache } from '../core/unified-cache.js';
+import { OrderStatus } from '../core/types.js';
+import { isTerminalStatus, isValidStatusTransition } from '../core/order-status.js';
+import { PolymarketError, ErrorCode } from '../core/errors.js';
+// ============================================================================
+// OrderManager Implementation
+// ============================================================================
+export class OrderManager extends EventEmitter {
+    // ========== Polymarket Service Dependencies ==========
+    tradingService;
+    realtimeService = null;
+    polygonProvider = null;
+    // ========== Configuration ==========
+    config;
+    initialized = false;
+    // ========== Monitoring State ==========
+    watchedOrders = new Map();
+    processedEvents = new Set();
+    mode;
+    // ========== Market Metadata Cache (Polymarket-specific) ==========
+    marketCache = new Map();
+    constructor(config) {
+        super();
+        this.config = {
+            ...config,
+            chainId: config.chainId ?? 137,
+            mode: config.mode ?? 'hybrid',
+            pollingInterval: config.pollingInterval ?? 5000,
+            polygonRpcUrl: config.polygonRpcUrl ?? 'https://polygon-rpc.com',
+        };
+        this.mode = this.config.mode;
+        // Create default RateLimiter and Cache if not provided
+        const rateLimiter = config.rateLimiter || new RateLimiter();
+        const cache = config.cache || createUnifiedCache();
+        // Initialize TradingService (always needed)
+        this.tradingService = new TradingService(rateLimiter, cache, {
+            privateKey: config.privateKey,
+            chainId: this.config.chainId,
+        });
+    }
+    // ============================================================================
+    // Lifecycle Management
+    // ============================================================================
+    /**
+     * Initialize OrderManager
+     * - Initializes TradingService
+     * - Optionally initializes RealtimeService (for WebSocket mode)
+     * - Optionally initializes Polygon provider (for settlement tracking)
+     */
+    async start() {
+        if (this.initialized)
+            return;
+        // Initialize TradingService
+        await this.tradingService.initialize();
+        // Initialize Polygon provider for settlement tracking
+        // (Polymarket-specific: tracks CTF token transfers on Polygon)
+        if (this.config.polygonRpcUrl) {
+            this.polygonProvider = new ethers.providers.JsonRpcProvider(this.config.polygonRpcUrl);
+        }
+        this.initialized = true;
+        this.emit('initialized');
+    }
+    /**
+     * Stop OrderManager
+     * - Unwatch all orders
+     * - Disconnect WebSocket (if connected)
+     */
+    stop() {
+        // Stop all polling
+        for (const watched of this.watchedOrders.values()) {
+            if (watched.pollingIntervalId) {
+                clearInterval(watched.pollingIntervalId);
+            }
+        }
+        // Disconnect WebSocket
+        if (this.realtimeService) {
+            this.realtimeService.disconnect();
+            this.realtimeService = null;
+        }
+        this.watchedOrders.clear();
+        this.processedEvents.clear();
+        this.initialized = false;
+        this.emit('stopped');
+    }
+    // ============================================================================
+    // Public API - Order Operations
+    // ============================================================================
+    /**
+     * Create and submit a limit order
+     *
+     * Auto-validates (Polymarket-specific):
+     * - Market state (active, not closed)
+     * - USDC.e balance
+     * - Tick size (0.01)
+     * - Minimum size (5 shares)
+     * - Minimum value ($1)
+     *
+     * Auto-watches: Starts monitoring immediately after creation
+     *
+     * @param params Order parameters
+     * @param metadata Optional metadata for tracking
+     * @returns Order result with orderId or error
+     */
+    async createOrder(params, metadata) {
+        this.ensureInitialized();
+        // Validate order (Polymarket-specific checks)
+        try {
+            await this.validateOrder(params);
+        }
+        catch (error) {
+            const rejectEvent = {
+                params,
+                reason: error instanceof Error ? error.message : String(error),
+                timestamp: Date.now(),
+            };
+            this.emit('order_rejected', rejectEvent);
+            return {
+                success: false,
+                errorMsg: rejectEvent.reason,
+            };
+        }
+        // Submit order via TradingService
+        const result = await this.tradingService.createLimitOrder(params);
+        if (result.success && result.orderId) {
+            // Auto-watch the order
+            this.watchOrder(result.orderId, metadata);
+            // Emit order_created event
+            this.emit('order_created', {
+                id: result.orderId,
+                status: OrderStatus.PENDING,
+                tokenId: params.tokenId,
+                side: params.side,
+                price: params.price,
+                originalSize: params.size,
+                filledSize: 0,
+                remainingSize: params.size,
+                associateTrades: [],
+                createdAt: Date.now(),
+            });
+        }
+        return result;
+    }
+    /**
+     * Create and submit a market order (FOK or FAK)
+     *
+     * Market order lifecycle:
+     * - FOK (Fill Or Kill): Must fill completely or cancels immediately
+     *   PENDING → FILLED (success) or PENDING → CANCELLED (failed to fill)
+     * - FAK (Fill And Kill): Fills what it can, cancels the rest
+     *   PENDING → PARTIALLY_FILLED + CANCELLED (partial) or PENDING → FILLED (complete)
+     *
+     * Auto-validates (Polymarket-specific):
+     * - Minimum value ($1)
+     *
+     * Auto-watches: Starts monitoring immediately after creation
+     * Note: Market orders typically complete very quickly (within seconds)
+     *
+     * @param params Market order parameters
+     * @param metadata Optional metadata for tracking
+     * @returns Order result with orderId or error
+     */
+    async createMarketOrder(params, metadata) {
+        this.ensureInitialized();
+        // Validate market order (Polymarket-specific checks)
+        try {
+            await this.validateMarketOrder(params);
+        }
+        catch (error) {
+            const rejectEvent = {
+                params: params, // MarketOrderParams is compatible enough
+                reason: error instanceof Error ? error.message : String(error),
+                timestamp: Date.now(),
+            };
+            this.emit('order_rejected', rejectEvent);
+            return {
+                success: false,
+                errorMsg: rejectEvent.reason,
+            };
+        }
+        // Submit market order via TradingService
+        const result = await this.tradingService.createMarketOrder(params);
+        if (result.success && result.orderId) {
+            // Auto-watch the order
+            this.watchOrder(result.orderId, {
+                ...metadata,
+                orderType: params.orderType || 'FOK', // Track order type for lifecycle handling
+            });
+            // Emit order_created event
+            this.emit('order_created', {
+                id: result.orderId,
+                status: OrderStatus.PENDING,
+                tokenId: params.tokenId,
+                side: params.side,
+                price: params.price || 0, // Market orders may not have a fixed price
+                originalSize: params.amount, // For market orders, amount is in USDC
+                filledSize: 0,
+                remainingSize: params.amount,
+                associateTrades: [],
+                createdAt: Date.now(),
+                orderType: params.orderType || 'FOK',
+            });
+        }
+        return result;
+    }
+    /**
+     * Cancel an order
+     * Auto-unwatches after cancellation
+     */
+    async cancelOrder(orderId) {
+        this.ensureInitialized();
+        const result = await this.tradingService.cancelOrder(orderId);
+        if (result.success) {
+            // Unwatch order (will stop polling/listening)
+            this.unwatchOrder(orderId);
+        }
+        return result;
+    }
+    /**
+     * Get order details
+     * Fetches from TradingService (CLOB API)
+     */
+    async getOrder(orderId) {
+        this.ensureInitialized();
+        return this.tradingService.getOrder(orderId);
+    }
+    /**
+     * Create multiple orders in batch
+     * Auto-watches all successfully created orders
+     */
+    async createBatchOrders(orders, metadata) {
+        this.ensureInitialized();
+        const result = await this.tradingService.createBatchOrders(orders);
+        if (result.success && result.orderIds) {
+            // Auto-watch all created orders
+            for (const orderId of result.orderIds) {
+                this.watchOrder(orderId, metadata);
+            }
+        }
+        return result;
+    }
+    // ============================================================================
+    // Public API - Order Monitoring
+    // ============================================================================
+    /**
+     * Manually watch an order
+     * Used for monitoring externally-created orders
+     *
+     * @param orderId Order ID to watch
+     * @param metadata Optional metadata
+     */
+    watchOrder(orderId, metadata) {
+        if (this.watchedOrders.has(orderId)) {
+            return; // Already watching
+        }
+        // Create initial watched state
+        const watched = {
+            orderId,
+            order: {
+                id: orderId,
+                status: OrderStatus.PENDING,
+                tokenId: '',
+                side: 'BUY',
+                price: 0,
+                originalSize: 0,
+                filledSize: 0,
+                remainingSize: 0,
+                associateTrades: [],
+                createdAt: Date.now(),
+            },
+            metadata,
+            lastStatus: OrderStatus.PENDING,
+        };
+        this.watchedOrders.set(orderId, watched);
+        // Start monitoring based on mode
+        if (this.mode === 'websocket' || this.mode === 'hybrid') {
+            // Fire and forget - WebSocket connection is lazy initialized
+            this.ensureWebSocketConnected().catch(err => {
+                this.emit('error', new Error(`Failed to establish WebSocket connection: ${err.message}`));
+            });
+        }
+        if (this.mode === 'polling' || this.mode === 'hybrid') {
+            this.startPolling(orderId);
+        }
+        this.emit('watch_started', orderId);
+    }
+    /**
+     * Stop watching an order
+     */
+    unwatchOrder(orderId) {
+        const watched = this.watchedOrders.get(orderId);
+        if (!watched)
+            return;
+        // Stop polling if active
+        if (watched.pollingIntervalId) {
+            clearInterval(watched.pollingIntervalId);
+        }
+        this.watchedOrders.delete(orderId);
+        this.emit('watch_stopped', orderId);
+    }
+    /**
+     * Get all watched orders
+     */
+    getWatchedOrders() {
+        return Array.from(this.watchedOrders.values()).map((w) => w.order);
+    }
+    /**
+     * Get watched order by ID
+     */
+    getWatchedOrder(orderId) {
+        return this.watchedOrders.get(orderId)?.order;
+    }
+    // ============================================================================
+    // Private - Order Validation (Polymarket-specific)
+    // ============================================================================
+    /**
+     * Validate order parameters before submission
+     * All checks here are Polymarket-specific
+     */
+    async validateOrder(params) {
+        // 1. Tick size validation (Polymarket: 0.01)
+        // Use integer math to avoid floating point precision issues
+        const priceInCents = Math.round(params.price * 100);
+        const epsilon = 0.001; // Tolerance for floating point errors
+        if (Math.abs(priceInCents - params.price * 100) > epsilon) {
+            throw new PolymarketError(ErrorCode.ORDER_REJECTED, `Price must be multiple of 0.01 tick size (got ${params.price})`);
+        }
+        // 2. Minimum size validation (Polymarket: 5 shares)
+        if (params.size < 5) {
+            throw new PolymarketError(ErrorCode.ORDER_REJECTED, `Size must be at least 5 shares (got ${params.size})`);
+        }
+        // 3. Minimum value validation (Polymarket: $1)
+        const orderValue = params.price * params.size;
+        if (orderValue < 1) {
+            throw new PolymarketError(ErrorCode.ORDER_REJECTED, `Order value must be at least $1 (got $${orderValue.toFixed(2)})`);
+        }
+        // Note: Balance and market state checks would require additional service dependencies
+        // For now, we rely on TradingService validation
+    }
+    /**
+     * Validate market order parameters before submission
+     * Market orders have simpler validation than limit orders
+     */
+    async validateMarketOrder(params) {
+        // 1. Minimum value validation (Polymarket: $1)
+        if (params.amount < 1) {
+            throw new PolymarketError(ErrorCode.ORDER_REJECTED, `Order amount must be at least $1 (got $${params.amount.toFixed(2)})`);
+        }
+        // 2. Validate order type if specified
+        if (params.orderType && !['FOK', 'FAK'].includes(params.orderType)) {
+            throw new PolymarketError(ErrorCode.ORDER_REJECTED, `Invalid market order type: ${params.orderType}. Must be FOK or FAK.`);
+        }
+        // Note: Price validation is optional for market orders
+        // If price is provided, it's used as a limit price (max for BUY, min for SELL)
+    }
+    // ============================================================================
+    // Private - WebSocket Monitoring (Polymarket-specific)
+    // ============================================================================
+    /**
+     * Ensure WebSocket connection is established
+     * Lazy initialization of RealtimeService
+     */
+    async ensureWebSocketConnected() {
+        if (this.realtimeService)
+            return;
+        // Import and initialize RealtimeServiceV2
+        // (We use dynamic import to avoid circular dependencies)
+        const { RealtimeServiceV2 } = await import('./realtime-service-v2.js');
+        this.realtimeService = new RealtimeServiceV2({ autoReconnect: true });
+        // Connect to WebSocket
+        if (this.realtimeService) {
+            this.realtimeService.connect();
+        }
+        // Subscribe to user events (requires credentials)
+        const credentials = this.tradingService.getCredentials();
+        if (credentials && this.realtimeService) {
+            this.realtimeService.subscribeUserEvents(credentials, {
+                onOrder: this.handleUserOrder.bind(this),
+                onTrade: this.handleUserTrade.bind(this),
+            });
+        }
+    }
+    /**
+     * Handle USER_ORDER WebSocket event (Polymarket-specific)
+     * Triggered on: PLACEMENT, UPDATE, CANCELLATION
+     */
+    handleUserOrder(userOrder) {
+        const watched = this.watchedOrders.get(userOrder.orderId);
+        if (!watched)
+            return; // Not watching this order
+        // Deduplicate events
+        const eventKey = `order_${userOrder.orderId}_${userOrder.timestamp}_${userOrder.eventType}`;
+        if (this.processedEvents.has(eventKey))
+            return;
+        this.processedEvents.add(eventKey);
+        // Update order state
+        watched.order.price = userOrder.price;
+        watched.order.originalSize = userOrder.originalSize;
+        watched.order.filledSize = userOrder.matchedSize;
+        watched.order.remainingSize = userOrder.originalSize - userOrder.matchedSize;
+        // Infer new status
+        let newStatus = watched.lastStatus;
+        if (userOrder.eventType === 'PLACEMENT') {
+            newStatus = OrderStatus.OPEN;
+        }
+        else if (userOrder.eventType === 'UPDATE') {
+            if (userOrder.matchedSize > 0) {
+                newStatus =
+                    userOrder.matchedSize >= userOrder.originalSize
+                        ? OrderStatus.FILLED
+                        : OrderStatus.PARTIALLY_FILLED;
+            }
+        }
+        else if (userOrder.eventType === 'CANCELLATION') {
+            newStatus = OrderStatus.CANCELLED;
+        }
+        // Emit status change if changed
+        if (newStatus !== watched.lastStatus) {
+            this.emitStatusChange(watched, newStatus, 'websocket');
+        }
+    }
+    /**
+     * Handle USER_TRADE WebSocket event (Polymarket-specific)
+     * Triggered when: MATCHED, MINED, CONFIRMED
+     */
+    async handleUserTrade(userTrade) {
+        const watched = this.watchedOrders.get(userTrade.market);
+        if (!watched)
+            return;
+        // Deduplicate events
+        const eventKey = `trade_${userTrade.tradeId}_${userTrade.status}_${userTrade.timestamp}`;
+        if (this.processedEvents.has(eventKey))
+            return;
+        this.processedEvents.add(eventKey);
+        // Emit fill event
+        const isCompleteFill = watched.order.filledSize + userTrade.size >= watched.order.originalSize;
+        const fillEvent = {
+            orderId: watched.orderId,
+            order: watched.order,
+            fill: {
+                tradeId: userTrade.tradeId,
+                size: userTrade.size,
+                price: userTrade.price,
+                fee: 0, // Fee info not in UserTrade
+                timestamp: userTrade.timestamp,
+                transactionHash: userTrade.transactionHash,
+            },
+            cumulativeFilled: watched.order.filledSize + userTrade.size,
+            remainingSize: watched.order.originalSize - (watched.order.filledSize + userTrade.size),
+            isCompleteFill,
+        };
+        if (isCompleteFill) {
+            this.emit('order_filled', fillEvent);
+        }
+        else {
+            this.emit('order_partially_filled', fillEvent);
+        }
+        // If trade has transaction hash, emit transaction event
+        if (userTrade.transactionHash) {
+            const txEvent = {
+                orderId: watched.orderId,
+                tradeId: userTrade.tradeId,
+                transactionHash: userTrade.transactionHash,
+                timestamp: Date.now(),
+            };
+            this.emit('transaction_submitted', txEvent);
+            // Start tracking settlement on Polygon
+            if (userTrade.status === 'CONFIRMED') {
+                await this.trackSettlement(userTrade.tradeId, userTrade.transactionHash, watched.orderId);
+            }
+        }
+    }
+    // ============================================================================
+    // Private - Polling Monitoring
+    // ============================================================================
+    /**
+     * Start polling for order status
+     * Fallback mechanism when WebSocket is unavailable
+     */
+    startPolling(orderId) {
+        const watched = this.watchedOrders.get(orderId);
+        if (!watched || watched.pollingIntervalId)
+            return;
+        const poll = async () => {
+            try {
+                const order = await this.tradingService.getOrder(orderId);
+                if (order) {
+                    this.updateWatchedOrder(orderId, order);
+                }
+            }
+            catch (error) {
+                this.emit('error', new Error(`Polling error for ${orderId}: ${error}`));
+            }
+        };
+        // Initial poll
+        poll();
+        // Set up interval
+        watched.pollingIntervalId = setInterval(poll, this.config.pollingInterval);
+    }
+    /**
+     * Update watched order from polling result
+     * Detects both status changes and fill changes
+     */
+    updateWatchedOrder(orderId, freshOrder) {
+        const watched = this.watchedOrders.get(orderId);
+        if (!watched)
+            return;
+        const oldStatus = watched.lastStatus;
+        const oldFilledSize = watched.order.filledSize;
+        const newStatus = freshOrder.status;
+        const newFilledSize = freshOrder.filledSize;
+        // Detect fill changes (size increased)
+        // Only emit if this is an actual increase from a previously known state
+        if (newFilledSize > oldFilledSize && oldFilledSize >= 0) {
+            const fillDelta = newFilledSize - oldFilledSize;
+            const isCompleteFill = freshOrder.remainingSize === 0;
+            // Deduplicate fill events using fill size as key
+            const eventKey = `fill_${orderId}_${newFilledSize}`;
+            if (!this.processedEvents.has(eventKey)) {
+                this.processedEvents.add(eventKey);
+                // Estimate fill price from order price or calculate from avg
+                // Note: OpenOrder doesn't have avgFillPrice, so we use order.price as estimate
+                const estimatedPrice = freshOrder.price;
+                const fillEvent = {
+                    orderId,
+                    order: freshOrder,
+                    fill: {
+                        tradeId: freshOrder.associateTrades[freshOrder.associateTrades.length - 1] || `polling_${Date.now()}`,
+                        size: fillDelta,
+                        price: estimatedPrice,
+                        fee: 0, // Fee info not available in polling
+                        timestamp: Date.now(),
+                    },
+                    cumulativeFilled: newFilledSize,
+                    remainingSize: freshOrder.remainingSize,
+                    isCompleteFill,
+                };
+                if (isCompleteFill) {
+                    this.emit('order_filled', fillEvent);
+                }
+                else {
+                    this.emit('order_partially_filled', fillEvent);
+                }
+            }
+        }
+        // Update order
+        watched.order = freshOrder;
+        // Emit status change if changed
+        // Pass flag to prevent duplicate fill events
+        if (newStatus !== oldStatus) {
+            this.emitStatusChange(watched, newStatus, 'polling', newFilledSize > oldFilledSize);
+        }
+    }
+    // ============================================================================
+    // Private - Status Change Emission
+    // ============================================================================
+    /**
+     * Emit status change event with appropriate specific events
+     * @param fillAlreadyEmitted - Set to true if fill event was already emitted (to prevent duplicates)
+     */
+    emitStatusChange(watched, newStatus, source, fillAlreadyEmitted = false) {
+        const oldStatus = watched.lastStatus;
+        // Validate transition
+        if (!isValidStatusTransition(oldStatus, newStatus)) {
+            this.emit('error', new Error(`Invalid status transition: ${oldStatus} → ${newStatus} for ${watched.orderId}`));
+            return;
+        }
+        // Update status
+        watched.lastStatus = newStatus;
+        watched.order.status = newStatus;
+        watched.order.updatedAt = Date.now();
+        // Emit generic status_change event
+        const changeEvent = {
+            orderId: watched.orderId,
+            from: oldStatus,
+            to: newStatus,
+            order: watched.order,
+            timestamp: Date.now(),
+            reason: source,
+        };
+        this.emit('status_change', changeEvent);
+        // Emit specific events
+        if (newStatus === OrderStatus.OPEN) {
+            this.emit('order_opened', watched.order);
+        }
+        else if (newStatus === OrderStatus.FILLED && !fillAlreadyEmitted) {
+            // Only emit fill event if not already emitted (from polling fill detection)
+            this.emit('order_filled', {
+                orderId: watched.orderId,
+                order: watched.order,
+                fill: {
+                    tradeId: watched.order.associateTrades[watched.order.associateTrades.length - 1] || '',
+                    size: watched.order.filledSize,
+                    price: watched.order.price,
+                    fee: 0,
+                    timestamp: Date.now(),
+                },
+                cumulativeFilled: watched.order.filledSize,
+                remainingSize: 0,
+                isCompleteFill: true,
+            });
+        }
+        else if (newStatus === OrderStatus.CANCELLED) {
+            const cancelEvent = {
+                orderId: watched.orderId,
+                order: watched.order,
+                filledSize: watched.order.filledSize,
+                cancelledSize: watched.order.remainingSize,
+                reason: 'user',
+                timestamp: Date.now(),
+            };
+            this.emit('order_cancelled', cancelEvent);
+        }
+        else if (newStatus === OrderStatus.EXPIRED) {
+            const expireEvent = {
+                orderId: watched.orderId,
+                order: watched.order,
+                filledSize: watched.order.filledSize,
+                expiredSize: watched.order.remainingSize,
+                expirationTime: watched.order.expiration || 0,
+                timestamp: Date.now(),
+            };
+            this.emit('order_expired', expireEvent);
+        }
+        // Auto-unwatch terminal states
+        if (isTerminalStatus(newStatus)) {
+            this.unwatchOrder(watched.orderId);
+        }
+    }
+    // ============================================================================
+    // Private - Chain Settlement Tracking (Polymarket-specific)
+    // ============================================================================
+    /**
+     * Track transaction settlement on Polygon blockchain
+     * Waits for on-chain confirmation and emits transaction_confirmed event
+     */
+    async trackSettlement(tradeId, transactionHash, orderId) {
+        if (!this.polygonProvider) {
+            return; // No provider configured
+        }
+        try {
+            // Wait for 1 confirmation
+            const receipt = await this.polygonProvider.waitForTransaction(transactionHash, 1);
+            if (receipt) {
+                const settlementEvent = {
+                    orderId,
+                    tradeId,
+                    transactionHash,
+                    blockNumber: receipt.blockNumber,
+                    gasUsed: receipt.gasUsed.toString(),
+                    timestamp: Date.now(),
+                };
+                this.emit('transaction_confirmed', settlementEvent);
+            }
+        }
+        catch (error) {
+            this.emit('error', new Error(`Settlement tracking failed for ${transactionHash}: ${error}`));
+        }
+    }
+    // ============================================================================
+    // Private - Utilities
+    // ============================================================================
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new PolymarketError(ErrorCode.ORDER_FAILED, 'OrderManager not initialized. Call start() first.');
+        }
+    }
+}
+//# sourceMappingURL=order-manager.js.map