@catalyst-team/poly-sdk 0.1.0

package/src/__tests__/integration/clob-api.integration.test.ts

@@ -0,0 +1,218 @@
+/**
+ * CLOB API Client Integration Tests
+ *
+ * These tests make REAL API calls to Polymarket.
+ * They verify that:
+ * 1. API endpoints are reachable
+ * 2. Response structures match our types
+ * 3. Data normalization works correctly
+ *
+ * Run with: pnpm test:integration
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { ClobApiClient } from '../../clients/clob-api.js';
+import { RateLimiter } from '../../core/rate-limiter.js';
+import { createUnifiedCache } from '../../core/unified-cache.js';
+
+describe('ClobApiClient Integration', () => {
+  let client: ClobApiClient;
+
+  beforeAll(() => {
+    client = new ClobApiClient(new RateLimiter(), createUnifiedCache());
+  });
+
+  describe('getMarket', () => {
+    it('should fetch a real market from Polymarket', async () => {
+      // Get trending markets first to find a valid condition ID
+      const response = await fetch(
+        'https://gamma-api.polymarket.com/markets?active=true&limit=1&order=volume24hr&ascending=false'
+      );
+      const markets = await response.json() as Array<{ conditionId: string }>;
+
+      if (markets.length === 0) {
+        console.log('No active markets found, skipping test');
+        return;
+      }
+
+      const conditionId = markets[0].conditionId;
+      const market = await client.getMarket(conditionId);
+
+      // Verify structure
+      expect(market.conditionId).toBe(conditionId);
+      expect(typeof market.question).toBe('string');
+      expect(market.question.length).toBeGreaterThan(0);
+      expect(Array.isArray(market.tokens)).toBe(true);
+      expect(market.tokens.length).toBeGreaterThanOrEqual(2);
+
+      // Verify tokens
+      for (const token of market.tokens) {
+        expect(typeof token.tokenId).toBe('string');
+        expect(token.tokenId.length).toBeGreaterThan(0);
+        expect(['Yes', 'No']).toContain(token.outcome);
+        expect(typeof token.price).toBe('number');
+        expect(token.price).toBeGreaterThanOrEqual(0);
+        expect(token.price).toBeLessThanOrEqual(1);
+      }
+
+      // Verify other fields
+      expect(typeof market.active).toBe('boolean');
+      expect(typeof market.closed).toBe('boolean');
+      expect(typeof market.acceptingOrders).toBe('boolean');
+
+      console.log(`✓ Successfully fetched market: "${market.question.slice(0, 50)}..."`);
+    }, 30000);
+
+    it('should handle non-existent market gracefully', async () => {
+      await expect(
+        client.getMarket('0x0000000000000000000000000000000000000000000000000000000000000000')
+      ).rejects.toThrow();
+    }, 30000);
+  });
+
+  describe('getOrderbook', () => {
+    it('should fetch real orderbook data', async () => {
+      // First get a market to get token ID
+      const response = await fetch(
+        'https://gamma-api.polymarket.com/markets?active=true&limit=1&order=volume24hr&ascending=false'
+      );
+      const markets = await response.json() as Array<{ conditionId: string }>;
+
+      if (markets.length === 0) {
+        console.log('No active markets found, skipping test');
+        return;
+      }
+
+      const market = await client.getMarket(markets[0].conditionId);
+      const yesToken = market.tokens.find(t => t.outcome === 'Yes');
+
+      if (!yesToken) {
+        console.log('No YES token found, skipping test');
+        return;
+      }
+
+      const orderbook = await client.getOrderbook(yesToken.tokenId);
+
+      // Verify structure
+      expect(Array.isArray(orderbook.bids)).toBe(true);
+      expect(Array.isArray(orderbook.asks)).toBe(true);
+      expect(typeof orderbook.timestamp).toBe('number');
+      expect(orderbook.timestamp).toBeGreaterThan(0);
+
+      // Verify bids are sorted descending (if any exist)
+      for (let i = 1; i < orderbook.bids.length; i++) {
+        expect(orderbook.bids[i].price).toBeLessThanOrEqual(orderbook.bids[i - 1].price);
+      }
+
+      // Verify asks are sorted ascending (if any exist)
+      for (let i = 1; i < orderbook.asks.length; i++) {
+        expect(orderbook.asks[i].price).toBeGreaterThanOrEqual(orderbook.asks[i - 1].price);
+      }
+
+      // Verify price/size types
+      if (orderbook.bids.length > 0) {
+        expect(typeof orderbook.bids[0].price).toBe('number');
+        expect(typeof orderbook.bids[0].size).toBe('number');
+        expect(orderbook.bids[0].price).toBeGreaterThan(0);
+        expect(orderbook.bids[0].price).toBeLessThan(1);
+      }
+
+      console.log(`✓ Orderbook: ${orderbook.bids.length} bids, ${orderbook.asks.length} asks`);
+    }, 30000);
+  });
+
+  describe('getProcessedOrderbook', () => {
+    it('should return complete processed orderbook with analytics', async () => {
+      // Get an active market
+      const response = await fetch(
+        'https://gamma-api.polymarket.com/markets?active=true&limit=5&order=volume24hr&ascending=false'
+      );
+      const markets = await response.json() as Array<{ conditionId: string; question: string }>;
+
+      // Find a market with good liquidity
+      let processed = null;
+      for (const m of markets) {
+        try {
+          processed = await client.getProcessedOrderbook(m.conditionId);
+          if (processed.yes.bid > 0 && processed.yes.ask < 1) {
+            console.log(`✓ Using market: "${m.question.slice(0, 50)}..."`);
+            break;
+          }
+        } catch {
+          continue;
+        }
+      }
+
+      if (!processed) {
+        console.log('No liquid market found, skipping test');
+        return;
+      }
+
+      // Verify YES orderbook
+      expect(typeof processed.yes.bid).toBe('number');
+      expect(typeof processed.yes.ask).toBe('number');
+      expect(processed.yes.bid).toBeLessThanOrEqual(processed.yes.ask);
+
+      // Verify NO orderbook
+      expect(typeof processed.no.bid).toBe('number');
+      expect(typeof processed.no.ask).toBe('number');
+      expect(processed.no.bid).toBeLessThanOrEqual(processed.no.ask);
+
+      // Verify summary
+      expect(typeof processed.summary.effectiveLongCost).toBe('number');
+      expect(typeof processed.summary.effectiveShortRevenue).toBe('number');
+      expect(typeof processed.summary.longArbProfit).toBe('number');
+      expect(typeof processed.summary.shortArbProfit).toBe('number');
+
+      // Verify effective prices
+      expect(typeof processed.summary.effectivePrices.effectiveBuyYes).toBe('number');
+      expect(typeof processed.summary.effectivePrices.effectiveBuyNo).toBe('number');
+      expect(typeof processed.summary.effectivePrices.effectiveSellYes).toBe('number');
+      expect(typeof processed.summary.effectivePrices.effectiveSellNo).toBe('number');
+
+      // Log arbitrage info
+      console.log(`  YES: bid=${processed.yes.bid.toFixed(3)}, ask=${processed.yes.ask.toFixed(3)}`);
+      console.log(`  NO:  bid=${processed.no.bid.toFixed(3)}, ask=${processed.no.ask.toFixed(3)}`);
+      console.log(`  Long arb profit:  ${(processed.summary.longArbProfit * 100).toFixed(3)}%`);
+      console.log(`  Short arb profit: ${(processed.summary.shortArbProfit * 100).toFixed(3)}%`);
+    }, 60000);
+
+    it('should correctly calculate effective prices with mirroring', async () => {
+      const response = await fetch(
+        'https://gamma-api.polymarket.com/markets?active=true&limit=1&order=volume24hr&ascending=false'
+      );
+      const markets = await response.json() as Array<{ conditionId: string }>;
+
+      if (markets.length === 0) return;
+
+      const processed = await client.getProcessedOrderbook(markets[0].conditionId);
+
+      // Verify mirroring logic:
+      // effectiveBuyYes should be <= YES.ask (can't be worse than direct buy)
+      expect(processed.summary.effectivePrices.effectiveBuyYes).toBeLessThanOrEqual(processed.yes.ask || 1);
+
+      // effectiveBuyNo should be <= NO.ask
+      expect(processed.summary.effectivePrices.effectiveBuyNo).toBeLessThanOrEqual(processed.no.ask || 1);
+
+      // effectiveSellYes should be >= YES.bid (can't be worse than direct sell)
+      expect(processed.summary.effectivePrices.effectiveSellYes).toBeGreaterThanOrEqual(processed.yes.bid);
+
+      // effectiveSellNo should be >= NO.bid
+      expect(processed.summary.effectivePrices.effectiveSellNo).toBeGreaterThanOrEqual(processed.no.bid);
+
+      // Long cost should equal sum of effective buy prices
+      const expectedLongCost =
+        processed.summary.effectivePrices.effectiveBuyYes +
+        processed.summary.effectivePrices.effectiveBuyNo;
+      expect(processed.summary.effectiveLongCost).toBeCloseTo(expectedLongCost, 6);
+
+      // Short revenue should equal sum of effective sell prices
+      const expectedShortRevenue =
+        processed.summary.effectivePrices.effectiveSellYes +
+        processed.summary.effectivePrices.effectiveSellNo;
+      expect(processed.summary.effectiveShortRevenue).toBeCloseTo(expectedShortRevenue, 6);
+
+      console.log('✓ Effective price calculations verified');
+    }, 30000);
+  });
+});

package/src/__tests__/integration/ctf-client.integration.test.ts

@@ -0,0 +1,331 @@
+/**
+ * CTF Client Integration Tests
+ *
+ * These tests verify the CTF (Conditional Token Framework) implementation
+ * by making REAL on-chain calls to Polygon.
+ *
+ * IMPORTANT: These tests are READ-ONLY and do not require a wallet.
+ * They verify:
+ * 1. Contract addresses are correct
+ * 2. Position ID calculation is correct
+ * 3. Market resolution queries work
+ * 4. Balance queries work
+ *
+ * Run with: pnpm test:integration
+ */
+
+import { describe, it, expect } from 'vitest';
+import { ethers } from 'ethers';
+import {
+  CTF_CONTRACT,
+  USDC_CONTRACT,
+  NEG_RISK_CTF_EXCHANGE,
+  NEG_RISK_ADAPTER,
+  USDC_DECIMALS,
+} from '../../clients/ctf-client.js';
+
+// Public RPC for read-only tests
+const POLYGON_RPC = 'https://polygon-rpc.com';
+
+// Known addresses and markets for testing
+const KNOWN_WHALE_ADDRESS = '0x82a1b239c1ff9bc60a4c86caf5b6bdbd9fddfe20'; // Top trader
+const SECOND_CTF_CONTRACT = '0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E';
+
+// ABIs for testing
+const CTF_ABI = [
+  'function balanceOf(address account, uint256 positionId) view returns (uint256)',
+  'function payoutNumerators(bytes32 conditionId, uint256 outcomeIndex) view returns (uint256)',
+  'function payoutDenominator(bytes32 conditionId) view returns (uint256)',
+  'function getOutcomeSlotCount(bytes32 conditionId) view returns (uint256)',
+];
+
+const ERC20_ABI = [
+  'function balanceOf(address account) view returns (uint256)',
+  'function decimals() view returns (uint8)',
+  'function symbol() view returns (string)',
+];
+
+describe('CTF Contract Verification', () => {
+  const provider = new ethers.providers.JsonRpcProvider(POLYGON_RPC);
+
+  describe('Contract Addresses', () => {
+    it('should verify CTF contract is deployed and accessible', async () => {
+      const ctf = new ethers.Contract(CTF_CONTRACT, CTF_ABI, provider);
+
+      // Query a known condition ID to verify contract works
+      // Using a random condition ID should return 0 for unresolved markets
+      const testConditionId = '0x0000000000000000000000000000000000000000000000000000000000000001';
+      const denominator = await ctf.payoutDenominator(testConditionId);
+
+      // Should return 0 for non-existent/unresolved condition
+      expect(denominator.toNumber()).toBe(0);
+
+      console.log(`✓ CTF Contract verified at ${CTF_CONTRACT}`);
+    }, 30000);
+
+    it('should verify USDC contract is deployed', async () => {
+      const usdc = new ethers.Contract(USDC_CONTRACT, ERC20_ABI, provider);
+
+      const [decimals, symbol] = await Promise.all([
+        usdc.decimals(),
+        usdc.symbol(),
+      ]);
+
+      expect(decimals).toBe(USDC_DECIMALS);
+      expect(symbol).toBe('USDC');
+
+      console.log(`✓ USDC Contract verified at ${USDC_CONTRACT}`);
+      console.log(`  Symbol: ${symbol}, Decimals: ${decimals}`);
+    }, 30000);
+
+    it('should verify second CTF contract exists', async () => {
+      // The second contract address from Polymarket docs
+      // Note: This is the NegRisk CTF contract with a different ABI
+      // We just verify the contract code exists
+      const code = await provider.getCode(SECOND_CTF_CONTRACT);
+
+      expect(code).not.toBe('0x');
+      expect(code.length).toBeGreaterThan(10);
+
+      console.log(`✓ Second CTF Contract verified at ${SECOND_CTF_CONTRACT}`);
+      console.log(`  Contract code size: ${(code.length - 2) / 2} bytes`);
+      console.log('  Note: This is the NegRisk CTF contract (different ABI from standard CTF)');
+    }, 30000);
+
+    it('should verify NegRisk Adapter contract exists', async () => {
+      // Check contract code exists
+      const code = await provider.getCode(NEG_RISK_ADAPTER);
+
+      expect(code).not.toBe('0x');
+      expect(code.length).toBeGreaterThan(10);
+
+      console.log(`✓ NegRisk Adapter verified at ${NEG_RISK_ADAPTER}`);
+      console.log(`  Contract code size: ${(code.length - 2) / 2} bytes`);
+    }, 30000);
+
+    it('should verify NegRisk CTF Exchange contract exists', async () => {
+      const code = await provider.getCode(NEG_RISK_CTF_EXCHANGE);
+
+      expect(code).not.toBe('0x');
+      expect(code.length).toBeGreaterThan(10);
+
+      console.log(`✓ NegRisk CTF Exchange verified at ${NEG_RISK_CTF_EXCHANGE}`);
+      console.log(`  Contract code size: ${(code.length - 2) / 2} bytes`);
+    }, 30000);
+  });
+
+  describe('Position ID Calculation', () => {
+    it('should calculate position ID correctly', () => {
+      // This matches the Polymarket gist for positionId calculation
+      // https://gist.github.com/polymarket/1e12f0ac3e23400ca53ec9b6e1ba00ce
+
+      const conditionId = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef';
+      const indexSet = 1; // YES outcome
+
+      // Collection ID = keccak256(parentCollectionId, conditionId, indexSet)
+      const collectionId = ethers.utils.keccak256(
+        ethers.utils.defaultAbiCoder.encode(
+          ['bytes32', 'bytes32', 'uint256'],
+          [ethers.constants.HashZero, conditionId, indexSet]
+        )
+      );
+
+      // Position ID = keccak256(collateralToken, collectionId)
+      const positionId = ethers.utils.keccak256(
+        ethers.utils.defaultAbiCoder.encode(
+          ['address', 'bytes32'],
+          [USDC_CONTRACT, collectionId]
+        )
+      );
+
+      // Verify the calculation produces valid bytes32
+      expect(positionId).toMatch(/^0x[a-f0-9]{64}$/);
+      expect(collectionId).toMatch(/^0x[a-f0-9]{64}$/);
+
+      console.log('✓ Position ID calculation verified');
+      console.log(`  Condition ID: ${conditionId.slice(0, 20)}...`);
+      console.log(`  Collection ID: ${collectionId.slice(0, 20)}...`);
+      console.log(`  Position ID: ${positionId.slice(0, 20)}...`);
+    });
+
+    it('should produce different position IDs for YES and NO', () => {
+      const conditionId = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef';
+
+      // YES position (indexSet = 1)
+      const yesCollectionId = ethers.utils.keccak256(
+        ethers.utils.defaultAbiCoder.encode(
+          ['bytes32', 'bytes32', 'uint256'],
+          [ethers.constants.HashZero, conditionId, 1]
+        )
+      );
+      const yesPositionId = ethers.utils.keccak256(
+        ethers.utils.defaultAbiCoder.encode(
+          ['address', 'bytes32'],
+          [USDC_CONTRACT, yesCollectionId]
+        )
+      );
+
+      // NO position (indexSet = 2)
+      const noCollectionId = ethers.utils.keccak256(
+        ethers.utils.defaultAbiCoder.encode(
+          ['bytes32', 'bytes32', 'uint256'],
+          [ethers.constants.HashZero, conditionId, 2]
+        )
+      );
+      const noPositionId = ethers.utils.keccak256(
+        ethers.utils.defaultAbiCoder.encode(
+          ['address', 'bytes32'],
+          [USDC_CONTRACT, noCollectionId]
+        )
+      );
+
+      expect(yesPositionId).not.toBe(noPositionId);
+      expect(yesCollectionId).not.toBe(noCollectionId);
+
+      console.log('✓ YES and NO position IDs are different');
+      console.log(`  YES Position ID: ${yesPositionId.slice(0, 20)}...`);
+      console.log(`  NO Position ID:  ${noPositionId.slice(0, 20)}...`);
+    });
+  });
+
+  describe('Balance Queries', () => {
+    it('should query USDC balance for known whale', async () => {
+      const usdc = new ethers.Contract(USDC_CONTRACT, ERC20_ABI, provider);
+
+      const balance = await usdc.balanceOf(KNOWN_WHALE_ADDRESS);
+      const formattedBalance = ethers.utils.formatUnits(balance, USDC_DECIMALS);
+
+      expect(balance.gte(0)).toBe(true);
+
+      console.log(`✓ USDC balance query works`);
+      console.log(`  Whale ${KNOWN_WHALE_ADDRESS.slice(0, 10)}... has ${parseFloat(formattedBalance).toLocaleString()} USDC`);
+    }, 30000);
+
+    it('should query CTF token balance', async () => {
+      const ctf = new ethers.Contract(CTF_CONTRACT, CTF_ABI, provider);
+
+      // Use a known position ID (we'll use a random one, should return 0)
+      const randomPositionId = ethers.utils.keccak256(
+        ethers.utils.defaultAbiCoder.encode(
+          ['string'],
+          ['random-test-position']
+        )
+      );
+
+      const balance = await ctf.balanceOf(KNOWN_WHALE_ADDRESS, randomPositionId);
+
+      expect(balance.gte(0)).toBe(true);
+
+      console.log('✓ CTF balance query works');
+      console.log(`  Balance for random position: ${ethers.utils.formatUnits(balance, USDC_DECIMALS)}`);
+    }, 30000);
+  });
+
+  describe('Market Resolution', () => {
+    it('should query payout info for a real market condition', async () => {
+      // First get a real market from Gamma API to get a valid condition ID
+      const response = await fetch(
+        'https://gamma-api.polymarket.com/markets?closed=true&limit=1'
+      );
+      const markets = await response.json() as Array<{ conditionId: string; question: string }>;
+
+      if (markets.length === 0) {
+        console.log('No closed markets found, skipping test');
+        return;
+      }
+
+      const ctf = new ethers.Contract(CTF_CONTRACT, CTF_ABI, provider);
+      const conditionId = markets[0].conditionId;
+
+      try {
+        const [yesNumerator, noNumerator, denominator] = await Promise.all([
+          ctf.payoutNumerators(conditionId, 0),
+          ctf.payoutNumerators(conditionId, 1),
+          ctf.payoutDenominator(conditionId),
+        ]);
+
+        expect(yesNumerator.gte(0)).toBe(true);
+        expect(noNumerator.gte(0)).toBe(true);
+        expect(denominator.gte(0)).toBe(true);
+
+        const isResolved = denominator.gt(0);
+
+        console.log('✓ Market resolution query works');
+        console.log(`  Market: "${markets[0].question.slice(0, 40)}..."`);
+        console.log(`  Condition ID: ${conditionId.slice(0, 20)}...`);
+        console.log(`  Is resolved: ${isResolved}`);
+        if (isResolved) {
+          console.log(`  Payout numerators: [${yesNumerator.toString()}, ${noNumerator.toString()}]`);
+          console.log(`  Payout denominator: ${denominator.toString()}`);
+        }
+      } catch (error) {
+        // Some markets might be NegRisk markets with different contract
+        console.log('✓ Query attempted (market might be NegRisk type)');
+        console.log(`  Condition ID: ${conditionId.slice(0, 20)}...`);
+      }
+    }, 30000);
+  });
+
+  describe('Gas Price', () => {
+    it('should fetch current gas price', async () => {
+      const gasPrice = await provider.getGasPrice();
+      const gasPriceGwei = ethers.utils.formatUnits(gasPrice, 'gwei');
+
+      expect(gasPrice.gt(0)).toBe(true);
+
+      console.log('✓ Gas price fetched');
+      console.log(`  Current gas price: ${parseFloat(gasPriceGwei).toFixed(2)} gwei`);
+    }, 30000);
+  });
+});
+
+describe('CTF Architecture Understanding', () => {
+  it('should document the two-contract architecture', () => {
+    /**
+     * Polymarket uses TWO different CTF systems:
+     *
+     * 1. STANDARD CTF (0x4D97DCd97eC945f40cF65F87097ACe5EA0476045)
+     *    - Used for simple binary (Yes/No) markets
+     *    - Operations: split, merge, redeem
+     *    - Each market is independent
+     *
+     * 2. NEGRISK CTF (0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E)
+     *    - Used for "winner-take-all" events (elections, championships)
+     *    - Key innovation: NO shares can convert to YES shares in other markets
+     *    - Example: "Trump NO" can become "Biden YES + Harris YES + ..."
+     *
+     * Why NegRisk exists:
+     * - Capital efficiency: Don't need to buy YES in every candidate
+     * - Buying NO in one candidate = betting on all other candidates
+     * - The Negative Adapter (0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296) handles conversions
+     *
+     * Which contract to use:
+     * - Check the market's metadata to determine if it's a NegRisk market
+     * - Most simple Yes/No markets use Standard CTF
+     * - Multi-outcome events (elections, sports champions) may use NegRisk
+     */
+
+    console.log('✓ CTF Architecture Documented');
+    console.log('');
+    console.log('Standard CTF Contract:');
+    console.log(`  ${CTF_CONTRACT}`);
+    console.log('  - Simple Yes/No markets');
+    console.log('  - split/merge/redeem operations');
+    console.log('');
+    console.log('NegRisk CTF Contract:');
+    console.log(`  ${SECOND_CTF_CONTRACT}`);
+    console.log('  - Winner-take-all events');
+    console.log('  - NO shares convertible to YES in other markets');
+    console.log('');
+    console.log('NegRisk Adapter:');
+    console.log(`  ${NEG_RISK_ADAPTER}`);
+    console.log('  - Handles NO → YES conversions');
+    console.log('');
+    console.log('NegRisk CTF Exchange:');
+    console.log(`  ${NEG_RISK_CTF_EXCHANGE}`);
+    console.log('  - Trading for NegRisk markets');
+
+    // This test always passes - it's documentation
+    expect(true).toBe(true);
+  });
+});