@catalyst-team/poly-sdk 0.4.3 → 0.4.5

package/dist/src/services/order-manager.d.ts

@@ -0,0 +1,281 @@
+/**
+ * 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
+ *
+ * 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 order (auto-validates + auto-watches)
+ * const result = await orderMgr.createOrder({
+ *   tokenId: '0x...',
+ *   side: 'BUY',
+ *   price: 0.52,
+ *   size: 100,
+ * });
+ * ```
+ */
+import { EventEmitter } from 'events';
+import { type LimitOrderParams, type Order, type OrderResult } from './trading-service.js';
+import { RateLimiter } from '../core/rate-limiter.js';
+import type { UnifiedCache } from '../core/unified-cache.js';
+import { OrderStatus } from '../core/types.js';
+export interface OrderManagerConfig {
+    /** Private key for signing transactions */
+    privateKey: string;
+    /** Rate limiter for API calls */
+    rateLimiter: RateLimiter;
+    /** Cache for market metadata */
+    cache: UnifiedCache;
+    /** Chain ID (default: 137 Polygon mainnet) */
+    chainId?: number;
+    /** Detection mode for order status tracking */
+    mode?: 'websocket' | 'polling' | 'hybrid';
+    /** Polling interval in ms (default: 5000) */
+    pollingInterval?: number;
+    /** RPC URL for Polygon provider (for settlement tracking) */
+    polygonRpcUrl?: string;
+}
+/**
+ * Optional metadata for order tracking
+ * Can be used by strategies to attach context
+ */
+export interface OrderMetadata {
+    strategyId?: string;
+    marketSlug?: string;
+    notes?: string;
+    [key: string]: unknown;
+}
+/**
+ * Order status change event
+ * Emitted whenever an order transitions between states
+ */
+export interface OrderStatusChangeEvent {
+    orderId: string;
+    from: OrderStatus;
+    to: OrderStatus;
+    order: Order;
+    timestamp: number;
+    reason?: string;
+}
+/**
+ * Fill event
+ * Emitted when an order receives a fill (partial or complete)
+ */
+export interface FillEvent {
+    orderId: string;
+    order: Order;
+    fill: {
+        tradeId: string;
+        size: number;
+        price: number;
+        fee: number;
+        timestamp: number;
+        transactionHash?: string;
+    };
+    cumulativeFilled: number;
+    remainingSize: number;
+    isCompleteFill: boolean;
+}
+/**
+ * Transaction submitted event (Polymarket-specific)
+ * Emitted when a trade has a transaction hash
+ */
+export interface TransactionEvent {
+    orderId: string;
+    tradeId: string;
+    transactionHash: string;
+    timestamp: number;
+}
+/**
+ * On-chain settlement event (Polymarket-specific)
+ * Emitted when transaction is confirmed on Polygon
+ */
+export interface SettlementEvent {
+    orderId: string;
+    tradeId: string;
+    transactionHash: string;
+    blockNumber: number;
+    gasUsed: string;
+    timestamp: number;
+}
+/**
+ * Cancellation event
+ */
+export interface CancelEvent {
+    orderId: string;
+    order: Order;
+    filledSize: number;
+    cancelledSize: number;
+    reason: 'user' | 'system';
+    timestamp: number;
+}
+/**
+ * Expiration event (for GTD orders)
+ */
+export interface ExpireEvent {
+    orderId: string;
+    order: Order;
+    filledSize: number;
+    expiredSize: number;
+    expirationTime: number;
+    timestamp: number;
+}
+/**
+ * Rejection event (order failed validation)
+ */
+export interface RejectEvent {
+    orderId?: string;
+    params: LimitOrderParams;
+    reason: string;
+    timestamp: number;
+}
+export declare class OrderManager extends EventEmitter {
+    private tradingService;
+    private realtimeService;
+    private polygonProvider;
+    private config;
+    private initialized;
+    private watchedOrders;
+    private processedEvents;
+    private mode;
+    private marketCache;
+    constructor(config: OrderManagerConfig);
+    /**
+     * Initialize OrderManager
+     * - Initializes TradingService
+     * - Optionally initializes RealtimeService (for WebSocket mode)
+     * - Optionally initializes Polygon provider (for settlement tracking)
+     */
+    start(): Promise<void>;
+    /**
+     * Stop OrderManager
+     * - Unwatch all orders
+     * - Disconnect WebSocket (if connected)
+     */
+    stop(): void;
+    /**
+     * 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
+     */
+    createOrder(params: LimitOrderParams, metadata?: OrderMetadata): Promise<OrderResult>;
+    /**
+     * Cancel an order
+     * Auto-unwatches after cancellation
+     */
+    cancelOrder(orderId: string): Promise<OrderResult>;
+    /**
+     * Get order details
+     * Fetches from TradingService (CLOB API)
+     */
+    getOrder(orderId: string): Promise<Order | null>;
+    /**
+     * Create multiple orders in batch
+     * Auto-watches all successfully created orders
+     */
+    createBatchOrders(orders: LimitOrderParams[], metadata?: OrderMetadata): Promise<OrderResult>;
+    /**
+     * Manually watch an order
+     * Used for monitoring externally-created orders
+     *
+     * @param orderId Order ID to watch
+     * @param metadata Optional metadata
+     */
+    watchOrder(orderId: string, metadata?: OrderMetadata): void;
+    /**
+     * Stop watching an order
+     */
+    unwatchOrder(orderId: string): void;
+    /**
+     * Get all watched orders
+     */
+    getWatchedOrders(): Order[];
+    /**
+     * Get watched order by ID
+     */
+    getWatchedOrder(orderId: string): Order | undefined;
+    /**
+     * Validate order parameters before submission
+     * All checks here are Polymarket-specific
+     */
+    private validateOrder;
+    /**
+     * Ensure WebSocket connection is established
+     * Lazy initialization of RealtimeService
+     */
+    private ensureWebSocketConnected;
+    /**
+     * Handle USER_ORDER WebSocket event (Polymarket-specific)
+     * Triggered on: PLACEMENT, UPDATE, CANCELLATION
+     */
+    private handleUserOrder;
+    /**
+     * Handle USER_TRADE WebSocket event (Polymarket-specific)
+     * Triggered when: MATCHED, MINED, CONFIRMED
+     */
+    private handleUserTrade;
+    /**
+     * Start polling for order status
+     * Fallback mechanism when WebSocket is unavailable
+     */
+    private startPolling;
+    /**
+     * Update watched order from polling result
+     * Detects both status changes and fill changes
+     */
+    private updateWatchedOrder;
+    /**
+     * Emit status change event with appropriate specific events
+     * @param fillAlreadyEmitted - Set to true if fill event was already emitted (to prevent duplicates)
+     */
+    private emitStatusChange;
+    /**
+     * Track transaction settlement on Polygon blockchain
+     * Waits for on-chain confirmation and emits transaction_confirmed event
+     */
+    private trackSettlement;
+    private ensureInitialized;
+}
+//# sourceMappingURL=order-manager.d.ts.map

package/dist/src/services/order-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"order-manager.d.ts","sourceRoot":"","sources":["../../../src/services/order-manager.ts"],"names":[],"mappings":"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"}