@catalyst-team/poly-sdk 0.1.0 → 0.2.0

package/docs/02-API.md

@@ -1,4 +1,4 @@
-# @prediction-router/poly-sdk API Reference
+# @catalyst-team/poly-sdk API Reference
 
 Complete API documentation for the Polymarket SDK.
 
@@ -29,13 +29,13 @@ Complete API documentation for the Polymarket SDK.
 ## Installation
 
 ```bash
-pnpm add @prediction-router/poly-sdk
+pnpm add @catalyst-team/poly-sdk
 ```
 
 ## Quick Start
 
 ```typescript
-import { PolymarketSDK } from '@prediction-router/poly-sdk';
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
 
 const sdk = new PolymarketSDK();
 
@@ -57,7 +57,7 @@ console.log('Long arb profit:', orderbook.summary.longArbProfit);
 The main SDK class that provides access to all API clients.
 
 ```typescript
-import { PolymarketSDK } from '@prediction-router/poly-sdk';
+import { PolymarketSDK } from '@catalyst-team/poly-sdk';
 
 const sdk = new PolymarketSDK(config?: PolymarketSDKConfig);
 ```
@@ -85,7 +85,7 @@ const sdk = new PolymarketSDK(config?: PolymarketSDKConfig);
 Central Limit Order Book (CLOB) API client for orderbook and market data.
 
 ```typescript
-import { ClobApiClient, RateLimiter, Cache } from '@prediction-router/poly-sdk';
+import { ClobApiClient, RateLimiter, Cache } from '@catalyst-team/poly-sdk';
 
 const client = new ClobApiClient(
   rateLimiter: RateLimiter,
@@ -175,7 +175,7 @@ Correct arbitrage calculation uses "effective prices":
 Market discovery and metadata API client.
 
 ```typescript
-import { GammaApiClient, RateLimiter, Cache } from '@prediction-router/poly-sdk';
+import { GammaApiClient, RateLimiter, Cache } from '@catalyst-team/poly-sdk';
 
 const client = new GammaApiClient(rateLimiter: RateLimiter, cache: Cache);
 ```
@@ -249,7 +249,7 @@ const events = await client.getEvents({ active: true, limit: 20 });
 User data, positions, and leaderboard API client.
 
 ```typescript
-import { DataApiClient, RateLimiter, Cache } from '@prediction-router/poly-sdk';
+import { DataApiClient, RateLimiter, Cache } from '@catalyst-team/poly-sdk';
 
 const client = new DataApiClient(rateLimiter: RateLimiter, cache: Cache);
 ```
@@ -308,7 +308,7 @@ for (const entry of leaderboard.entries) {
 Trading operations client (requires authentication).
 
 ```typescript
-import { TradingClient, RateLimiter } from '@prediction-router/poly-sdk';
+import { TradingClient, RateLimiter } from '@catalyst-team/poly-sdk';
 
 const client = new TradingClient(rateLimiter: RateLimiter, {
   privateKey: '0x...',
@@ -403,7 +403,7 @@ console.log(`USDC Balance: ${balance}`);
 Cross-chain deposit client for funding your Polymarket account.
 
 ```typescript
-import { BridgeClient } from '@prediction-router/poly-sdk';
+import { BridgeClient } from '@catalyst-team/poly-sdk';
 
 const bridge = new BridgeClient();
 ```
@@ -558,7 +558,7 @@ if (min) {
 
 ```typescript
 import { providers, Wallet, Contract, utils } from 'ethers';
-import { BridgeClient, BRIDGE_TOKENS } from '@prediction-router/poly-sdk';
+import { BridgeClient, BRIDGE_TOKENS } from '@catalyst-team/poly-sdk';
 
 // 1. Setup
 const provider = new providers.JsonRpcProvider('https://polygon-rpc.com');
@@ -591,7 +591,7 @@ console.log('Bridge fee: ~0.16%');
 CTF (Conditional Token Framework) client for on-chain token operations.
 
 ```typescript
-import { CTFClient } from '@prediction-router/poly-sdk';
+import { CTFClient } from '@catalyst-team/poly-sdk';
 
 const ctf = new CTFClient({
   privateKey: '0x...',
@@ -617,7 +617,7 @@ import {
   NEG_RISK_CTF_EXCHANGE, // 0xC5d563A36AE78145C45a50134d48A1215220f80a
   NEG_RISK_ADAPTER,     // 0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296
   USDC_DECIMALS,        // 6
-} from '@prediction-router/poly-sdk';
+} from '@catalyst-team/poly-sdk';
 ```
 
 #### Methods
@@ -655,7 +655,7 @@ console.log(`USDC received: ${result.usdcReceived}`);
 Get token balances using CLOB token IDs. **Recommended method.**
 
 ```typescript
-import type { TokenIds } from '@prediction-router/poly-sdk';
+import type { TokenIds } from '@catalyst-team/poly-sdk';
 
 // Get token IDs from CLOB API
 const market = await clobApi.getMarket('0xabc123...');
@@ -818,7 +818,7 @@ interface MarketResolution {
 #### CTF Arbitrage Example
 
 ```typescript
-import { CTFClient, ClobApiClient, TokenIds } from '@prediction-router/poly-sdk';
+import { CTFClient, ClobApiClient, TokenIds } from '@catalyst-team/poly-sdk';
 
 const ctf = new CTFClient({ privateKey, rpcUrl, chainId: 137 });
 const clobApi = new ClobApiClient(rateLimiter, cache);
@@ -864,7 +864,7 @@ if (ob.summary.shortArbProfit > 0.005) {
 Real-time market data via WebSocket.
 
 ```typescript
-import { WebSocketManager } from '@prediction-router/poly-sdk';
+import { WebSocketManager } from '@catalyst-team/poly-sdk';
 
 const ws = new WebSocketManager({ enableLogging: true });
 ```
@@ -909,7 +909,7 @@ Unsubscribe from all assets and cleanup.
 High-level market analysis service.
 
 ```typescript
-import { MarketService } from '@prediction-router/poly-sdk';
+import { MarketService } from '@catalyst-team/poly-sdk';
 
 const service = new MarketService(clobApi, gammaApi);
 
@@ -924,7 +924,7 @@ const analysis = await service.getMarketWithAnalysis('0x82ace55...');
 Arbitrage opportunity detection.
 
 ```typescript
-import { ArbitrageService } from '@prediction-router/poly-sdk';
+import { ArbitrageService } from '@catalyst-team/poly-sdk';
 
 const service = new ArbitrageService(clobApi, gammaApi);
 
@@ -946,7 +946,7 @@ for (const opp of opportunities) {
 High-level WebSocket subscription management.
 
 ```typescript
-import { RealtimeService, WebSocketManager } from '@prediction-router/poly-sdk';
+import { RealtimeService, WebSocketManager } from '@catalyst-team/poly-sdk';
 
 const ws = new WebSocketManager();
 const realtime = new RealtimeService(ws);
@@ -972,7 +972,7 @@ await sub.unsubscribe();
 Calculate effective prices accounting for orderbook mirroring.
 
 ```typescript
-import { getEffectivePrices } from '@prediction-router/poly-sdk';
+import { getEffectivePrices } from '@catalyst-team/poly-sdk';
 
 const effective = getEffectivePrices(0.57, 0.55, 0.45, 0.43);
 console.log('Effective buy YES:', effective.effectiveBuyYes);
@@ -986,7 +986,7 @@ console.log('Effective buy NO:', effective.effectiveBuyNo);
 Check for arbitrage opportunities.
 
 ```typescript
-import { checkArbitrage } from '@prediction-router/poly-sdk';
+import { checkArbitrage } from '@catalyst-team/poly-sdk';
 
 const arb = checkArbitrage(0.57, 0.55, 0.45, 0.43);
 if (arb.hasOpportunity) {
@@ -1107,7 +1107,7 @@ interface Position {
 The SDK uses `PolymarketError` for all errors.
 
 ```typescript
-import { PolymarketError, ErrorCode } from '@prediction-router/poly-sdk';
+import { PolymarketError, ErrorCode } from '@catalyst-team/poly-sdk';
 
 try {
   await client.getMarket('invalid-id');

package/docs/arb/test-plan.md

@@ -0,0 +1,387 @@
+# ArbitrageService E2E Test Plan
+
+> **Status**: In Progress
+> **Date**: 2024-12-24
+> **Author**: Claude Code
+
+## Overview
+
+This document outlines the comprehensive test plan for the ArbitrageService based on first principles understanding of the Polymarket arbitrage mechanism.
+
+## First Principles: Understanding the Arbitrage Mechanism
+
+### Core Concept: Mirror Orderbook
+
+Polymarket orderbooks have a critical property that's often misunderstood:
+
+```
+Buy YES @ P = Sell NO @ (1-P)
+```
+
+This means **the same order appears in both orderbooks**. Naive addition of prices leads to incorrect calculations.
+
+### Effective Prices
+
+To correctly calculate arbitrage opportunities, we must use **effective prices**:
+
+```typescript
+// Long Arb (Buy both + Merge)
+effectiveBuyYes = min(YES.ask, 1 - NO.bid)
+effectiveBuyNo = min(NO.ask, 1 - YES.bid)
+longCost = effectiveBuyYes + effectiveBuyNo
+longProfit = 1 - longCost  // > 0 means arbitrage exists
+
+// Short Arb (Split + Sell both)
+effectiveSellYes = max(YES.bid, 1 - NO.ask)
+effectiveSellNo = max(NO.bid, 1 - YES.ask)
+shortRevenue = effectiveSellYes + effectiveSellNo
+shortProfit = shortRevenue - 1  // > 0 means arbitrage exists
+```
+
+### Why We Need the Rebalancer
+
+Arbitrage execution requires:
+- **Long Arb**: USDC to buy tokens
+- **Short Arb**: YES + NO tokens to sell
+
+The Rebalancer maintains the optimal ratio:
+- USDC < 20% → Merge tokens to recover USDC
+- USDC > 80% → Split USDC to create tokens
+
+### Partial Fill Protection
+
+When buying both YES and NO in parallel, one order might succeed while the other fails:
+- `sizeSafetyFactor = 0.8` → Use only 80% of orderbook depth
+- `autoFixImbalance = true` → Auto-sell excess if imbalance occurs
+- `imbalanceThreshold = 5` → Trigger fix when YES-NO diff > $5
+
+---
+
+## Test Hierarchy
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  Level 1: Unit Tests (No Network)                                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  • getEffectivePrices() - Correct calculation of effective prices            │
+│  • checkArbitrage() - Correct arbitrage detection                            │
+│  • calculateRebalanceAction() - Rebalance strategy logic                     │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  Level 2: Integration Tests (Network, No Private Key)                        │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  • scanMarkets() - Market scanning and filtering                             │
+│  • WebSocket subscription - Real-time orderbook updates                      │
+│  • checkOpportunity() - Opportunity detection with real data                 │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  Level 3: E2E Tests (Real Market, With Private Key)                          │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  • Wallet connection and balance query                                       │
+│  • CTF Split/Merge operations                                                │
+│  • Order execution (small amounts)                                           │
+│  • Rebalancer functionality                                                  │
+│  • clearPositions() smart clearing                                           │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Test Cases
+
+### Level 1: Unit Tests
+
+#### Test 1.1: Effective Price Calculation
+```typescript
+// Input
+yesAsk = 0.52, yesBid = 0.48
+noAsk = 0.50, noBid = 0.46
+
+// Expected
+effectiveBuyYes = min(0.52, 1 - 0.46) = min(0.52, 0.54) = 0.52
+effectiveBuyNo = min(0.50, 1 - 0.48) = min(0.50, 0.52) = 0.50
+effectiveSellYes = max(0.48, 1 - 0.50) = max(0.48, 0.50) = 0.50
+effectiveSellNo = max(0.46, 1 - 0.52) = max(0.46, 0.48) = 0.48
+```
+
+#### Test 1.2: Long Arbitrage Detection
+```typescript
+// Scenario: Long arb exists
+yesAsk = 0.48, noAsk = 0.50, yesBid = 0.46, noBid = 0.48
+longCost = 0.48 + 0.50 = 0.98 < 1.00
+// Expected: longProfit = 0.02 (2%)
+```
+
+#### Test 1.3: Short Arbitrage Detection
+```typescript
+// Scenario: Short arb exists
+yesBid = 0.52, noBid = 0.50, yesAsk = 0.54, noAsk = 0.52
+shortRevenue = 0.52 + 0.50 = 1.02 > 1.00
+// Expected: shortProfit = 0.02 (2%)
+```
+
+#### Test 1.4: No Arbitrage (Normal Market)
+```typescript
+// Normal efficient market
+yesAsk = 0.52, yesBid = 0.48, noAsk = 0.52, noBid = 0.48
+longCost ≈ 1.02-1.04
+shortRevenue ≈ 0.96-0.98
+// Expected: No arbitrage opportunity
+```
+
+#### Test 1.5: Rebalance Action Calculation
+```typescript
+// Scenario: USDC too low
+usdc = 10, yesTokens = 80, noTokens = 80
+usdcRatio = 10 / (10 + 80) = 0.11 < 0.20
+// Expected: action = 'merge', reason = 'USDC 11% < 20% min'
+
+// Scenario: USDC too high
+usdc = 90, yesTokens = 10, noTokens = 10
+usdcRatio = 90 / (90 + 10) = 0.90 > 0.80
+// Expected: action = 'split', reason = 'USDC 90% > 80% max'
+
+// Scenario: Token imbalance
+yesTokens = 60, noTokens = 45
+imbalance = 15 > threshold(5)
+// Expected: action = 'sell_yes', priority = 100 (highest)
+```
+
+---
+
+### Level 2: Integration Tests
+
+#### Test 2.1: Market Scanning
+```typescript
+const service = new ArbitrageService({ enableLogging: true });
+
+const results = await service.scanMarkets({
+  minVolume24h: 5000,
+  limit: 20
+}, 0.005);
+
+// Verify:
+// - Returns array of ScanResult
+// - Each result has valid market config
+// - Effective prices are calculated correctly
+// - Score is computed based on profit * volume
+```
+
+#### Test 2.2: WebSocket Monitoring
+```typescript
+const service = new ArbitrageService({ enableLogging: true });
+
+// Find a market to monitor
+const results = await service.quickScan(0, 1);
+const market = results[0].market;
+
+// Start monitoring (no private key = no execution)
+await service.start(market);
+
+// Wait for orderbook updates
+await new Promise(resolve => setTimeout(resolve, 10000));
+
+// Verify:
+// - Orderbook state is populated
+// - Events are emitted
+const orderbook = service.getOrderbook();
+// Should have bids/asks for both YES and NO
+```
+
+#### Test 2.3: Opportunity Detection
+```typescript
+// After monitoring for some time:
+const opportunity = service.checkOpportunity();
+
+// If opportunity exists:
+// - type is 'long' or 'short'
+// - profitRate > 0
+// - recommendedSize respects config limits
+// - description is accurate
+```
+
+---
+
+### Level 3: E2E Tests
+
+#### Test 3.1: Wallet Connection
+```typescript
+const service = new ArbitrageService({
+  privateKey: process.env.PRIVATE_KEY,
+  enableLogging: true,
+});
+
+// Find a market
+const results = await service.quickScan(0, 1);
+await service.start(results[0].market);
+
+// Verify:
+const balance = service.getBalance();
+console.log(`USDC: ${balance.usdc}`);
+console.log(`YES: ${balance.yesTokens}`);
+console.log(`NO: ${balance.noTokens}`);
+
+// Expected: All balance fields are populated
+```
+
+#### Test 3.2: CTF Split Operation
+```typescript
+import { CTFClient } from '@catalyst-team/poly-sdk';
+
+const ctf = new CTFClient({
+  privateKey: process.env.PRIVATE_KEY,
+});
+
+// Split a small amount
+const splitResult = await ctf.split(conditionId, '5'); // $5 USDC
+
+// Verify:
+// - txHash is returned
+// - Balance now has 5 YES + 5 NO tokens
+// - USDC decreased by $5
+```
+
+#### Test 3.3: CTF Merge Operation
+```typescript
+// After split, merge back
+const tokenIds = {
+  yesTokenId: market.yesTokenId,
+  noTokenId: market.noTokenId,
+};
+
+const mergeResult = await ctf.mergeByTokenIds(conditionId, tokenIds, '5');
+
+// Verify:
+// - txHash is returned
+// - YES and NO tokens decreased by 5
+// - USDC increased by $5
+```
+
+#### Test 3.4: Order Execution
+```typescript
+// Buy a small amount of YES tokens
+const buyResult = await tradingClient.createMarketOrder({
+  tokenId: market.yesTokenId,
+  side: 'BUY',
+  amount: 5, // $5 USDC
+  orderType: 'FOK',
+});
+
+// Verify:
+// - success is true
+// - orderId is returned
+// - Balance reflects the purchase
+```
+
+#### Test 3.5: Rebalancer
+```typescript
+const service = new ArbitrageService({
+  privateKey: process.env.PRIVATE_KEY,
+  enableRebalancer: true,
+  minUsdcRatio: 0.2,
+  maxUsdcRatio: 0.8,
+  targetUsdcRatio: 0.5,
+});
+
+// Create imbalanced state (e.g., split all USDC)
+// Then let rebalancer run
+
+// Verify:
+// - Rebalance event is emitted
+// - Balance moves toward target ratio
+```
+
+#### Test 3.6: Clear Positions
+```typescript
+// After some operations, clear all positions
+const clearResult = await service.clearPositions(market, false);
+
+console.log('Plan:', clearResult.actions);
+console.log('Expected recovery:', clearResult.totalUsdcRecovered);
+
+// If executing:
+const executeResult = await service.clearPositions(market, true);
+// - Merged tokens are recovered as USDC
+// - Unpaired tokens are sold
+```
+
+---
+
+## Test Environment
+
+### Configuration
+```typescript
+// .env file
+PRIVATE_KEY=0x... // Test wallet private key
+
+// Test parameters
+MIN_TRADE_SIZE = 5     // Minimum $5 for safety
+MAX_TRADE_SIZE = 20    // Maximum $20 for safety
+PROFIT_THRESHOLD = 0   // Monitor all opportunities
+```
+
+### Safety Measures
+
+1. **Small amounts only**: All tests use $5-20 amounts
+2. **Monitor mode first**: Verify detection before execution
+3. **High profit threshold**: Production should use 0.5%+
+4. **Dry run first**: Use `execute = false` before real execution
+
+---
+
+## Execution Plan
+
+### Phase 1: Unit Tests (No Network)
+1. Create test file: `scripts/arb-tests/01-unit-tests.ts`
+2. Test price utilities
+3. Test rebalance logic
+4. Verify all calculations match expected values
+
+### Phase 2: Integration Tests (Network, No Execution)
+1. Create test file: `scripts/arb-tests/02-integration-tests.ts`
+2. Test market scanning
+3. Test WebSocket monitoring
+4. Verify opportunity detection on real data
+
+### Phase 3: E2E Tests (Real Execution)
+1. Create test file: `scripts/arb-tests/03-e2e-tests.ts`
+2. Test wallet connection
+3. Test CTF operations with small amounts
+4. Test order execution with small amounts
+5. Test clearPositions
+
+### Phase 4: Full Flow Test
+1. Create test file: `scripts/arb-tests/04-full-flow.ts`
+2. Scan → Select → Monitor → Execute → Clear
+3. Generate report
+
+---
+
+## Success Criteria
+
+| Test Level | Criteria |
+|------------|----------|
+| Unit | All calculations match expected values |
+| Integration | Market scanning returns valid results |
+| Integration | WebSocket receives orderbook updates |
+| E2E | Wallet balance is correctly queried |
+| E2E | Split/Merge operations succeed |
+| E2E | Order execution works |
+| E2E | clearPositions recovers funds |
+
+---
+
+## Risk Mitigation
+
+1. **Financial Risk**: Test with small amounts ($5-20 max)
+2. **Execution Risk**: Always dry-run first
+3. **Network Risk**: Handle errors gracefully
+4. **Timing Risk**: Use FOK orders to avoid partial fills
+
+---
+
+## Next Steps
+
+1. [x] Create test plan document
+2. [ ] Implement unit tests
+3. [ ] Implement integration tests
+4. [ ] Implement E2E tests
+5. [ ] Generate test report