@exponent-labs/exponent-sdk 0.1.8 → 0.9.0

package/src/orderbook/types.ts

@@ -1,4 +1,5 @@
-import { web3 } from "@coral-xyz/anchor"
+import { PublicKey } from "@solana/web3.js"
+import * as exponentOrderbook from '../client/orderbook'
 
 export type OrderbookLoadOptions = {
   syConfig?: {
@@ -6,24 +7,18 @@ export type OrderbookLoadOptions = {
   }
 }
 
-type EmptyObject = Record<never, never>
-export type OfferTypeAnchor = { buyYt: EmptyObject; sellYt?: never } | { sellYt: EmptyObject; buyYt?: never }
-
-export type OfferOptionsAnchor = { fillOrKill: { "0": boolean } }
-
-export enum OfferType {
-  SellYT = 1,
-  BuyYT = 2,
-}
+export const OfferType = exponentOrderbook.OfferType
+export type OfferType = exponentOrderbook.OfferType
 
 export type Offer = {
   type: OfferType
   priceApy: number
   amount: number
-  userEscrow: web3.PublicKey
+  userEscrow: PublicKey
   expiryAt: number
   createdAt: number
   isVirtual: boolean
+  offerIndex?: number
 }
 
 export enum OfferTradeDirection {

package/src/orderbook/utils.ts

@@ -1,10 +1,10 @@
-import { OfferType, OfferTradeDirection, OfferTypeAnchor, QuoteDirection } from "./types"
+import { OfferType, OfferTradeDirection, QuoteDirection } from "./types"
 
 /**
  * Get offer type by offer.orderTypeFlag value
  */
 export function getOfferType(orderTypeFlag: number): OfferType {
-  return orderTypeFlag === 1 ? OfferType.SellYT : OfferType.BuyYT
+  return orderTypeFlag === 1 ? OfferType.SellYt : OfferType.BuyYt
 }
 
 /**
@@ -22,9 +22,9 @@ export function getOfferTypeFromTradeDirection(tradeDirection: OfferTradeDirecti
 
   const offerType: OfferType = (() => {
     if (tradeDirection === OfferTradeDirection.SY_TO_YT || tradeDirection === OfferTradeDirection.PT_TO_SY) {
-      return OfferType.BuyYT
+      return OfferType.BuyYt
     } else {
-      return OfferType.SellYT
+      return OfferType.SellYt
     }
   })()
 
@@ -34,14 +34,6 @@ export function getOfferTypeFromTradeDirection(tradeDirection: OfferTradeDirecti
   }
 }
 
-export function convertOfferTypeToAnchorType(offerType: OfferType): OfferTypeAnchor {
-  return offerType === OfferType.BuyYT ? { buyYt: {} } : { sellYt: {} }
-}
-
-export function convertOfferTypeFromAnchorType(offerTypeAnchor: OfferTypeAnchor): OfferType {
-  return offerTypeAnchor?.buyYt ? OfferType.BuyYT : OfferType.SellYT
-}
-
 export function getOfferDirectionFromQuoteDirection(direction: QuoteDirection): OfferTradeDirection {
   switch (direction) {
     case QuoteDirection.BASE_TO_YT:

package/src/router.ts

@@ -1,5 +1,3 @@
-import { web3 } from "@coral-xyz/anchor"
-
 import { ExponentFetcher, MarketThree, Ticks } from "@exponent-labs/exponent-fetcher"
 import {
   QuoteDirection as ClmmQuoteDirection,
@@ -11,6 +9,21 @@ import { Environment } from "./environment"
 import { Market, MarketLoadOptions } from "./market"
 import { Orderbook, OrderbookLoadOptions, QuoteDirection as OrderbookQuoteDirection } from "./orderbook"
 import { Vault } from "./vault"
+import { Connection, PublicKey } from "@solana/web3.js"
+
+/** Configuration for split routing optimization */
+const SPLIT_ROUTING_CONFIG = {
+  /** Coarse grid step for initial search (percentage points) */
+  COARSE_STEP: 10,
+  /** Fine grid step for refinement (percentage points) */
+  FINE_STEP: 2,
+  /** Minimum allocation per route (percentage points) */
+  MIN_SPLIT_PERCENT: 5,
+  /** Maximum routes to consider */
+  MAX_ROUTES: 3,
+  /** Refinement range around best coarse result (percentage points) */
+  REFINEMENT_RANGE: 15,
+} as const
 
 export class Router {
   private legacyMarkets: Market[]
@@ -18,13 +31,13 @@ export class Router {
   private clmmsWithTicks: ClmmWithTicks[]
   //? For possible future use inside refetch functionality
   private vault: Vault | null
-  private connection: web3.Connection
+  private connection: Connection
 
   /**
    * Use the constructor if markets are already initialized in your app
    */
   constructor(
-    connection: web3.Connection,
+    connection: Connection,
     markets: { legacyMarkets?: Market[]; orderbooks?: Orderbook[]; clmmsWithTicks?: ClmmWithTicks[] },
     vault?: Vault,
   ) {
@@ -41,20 +54,20 @@ export class Router {
    * Use the load method if you don't have already loaded markets in your app
    */
   public static async load(
-    connection: web3.Connection,
+    connection: Connection,
     args: {
       vault?: Vault
       env: Environment
       legacyMarketsParams?: {
-        address: web3.PublicKey
+        address: PublicKey
         options?: MarketLoadOptions
       }[]
       orderbookParams?: {
-        address: web3.PublicKey
+        address: PublicKey
         options?: OrderbookLoadOptions
       }[]
       clmmParams?: {
-        marketThreeAddress: web3.PublicKey
+        marketThreeAddress: PublicKey
       }[]
     },
   ): Promise<Router> {
@@ -123,13 +136,290 @@ export class Router {
     return bestQuote
   }
 
+  /**
+   * Gets the best quote by potentially splitting the order across multiple venues (orderbooks and CLMMs only).
+   * Uses a two-phase optimization: coarse grid search followed by local refinement.
+   *
+   * @param params.direction - Trade direction
+   * @param params.inAmount - Total input amount to trade
+   * @param params.syExchangeRate - Current SY exchange rate
+   * @param params.maxRoutes - Maximum number of routes (1-3, default 3)
+   * @param params.minSplitPercent - Minimum allocation per route in percent (default 5)
+   * @returns Best split quote or null if no valid routes found
+   */
+  public getSplitQuote(params: {
+    direction: RouterQuoteDirection
+    inAmount: number
+    syExchangeRate: number
+    maxRoutes?: 1 | 2 | 3
+    minSplitPercent?: number
+  }): SplitQuote | null {
+    const {
+      direction,
+      inAmount,
+      syExchangeRate,
+      maxRoutes = SPLIT_ROUTING_CONFIG.MAX_ROUTES,
+      minSplitPercent = SPLIT_ROUTING_CONFIG.MIN_SPLIT_PERCENT,
+    } = params
+
+    // Build venue list (orderbooks + CLMMs only, no legacy markets)
+    const venues = this.buildVenueList()
+    if (venues.length === 0) return null
+
+    // Single venue: no split needed
+    if (venues.length === 1 || maxRoutes === 1) {
+      return this.getBestSingleVenueQuote(venues, direction, inAmount, syExchangeRate)
+    }
+
+    // Multi-venue optimization
+    const effectiveMaxRoutes = Math.min(maxRoutes, venues.length) as 1 | 2 | 3
+    let bestSplitQuote: SplitQuote | null = null
+
+    // Evaluate all venue combinations from 1 to maxRoutes
+    for (let numRoutes = 1; numRoutes <= effectiveMaxRoutes; numRoutes++) {
+      const combinations = generateCombinations(venues.length, numRoutes)
+
+      for (const venueIndices of combinations) {
+        const selectedVenues = venueIndices.map((i) => venues[i])
+        const quote = this.optimizeSplitForVenues(selectedVenues, direction, inAmount, syExchangeRate, minSplitPercent)
+
+        if (quote && (!bestSplitQuote || quote.totalOutAmount > bestSplitQuote.totalOutAmount)) {
+          bestSplitQuote = quote
+        }
+      }
+    }
+
+    return bestSplitQuote
+  }
+
+  /**
+   * Builds a unified list of venues (orderbooks + CLMMs) for split routing
+   */
+  private buildVenueList(): SplitVenue[] {
+    const orderbookVenues: SplitVenue[] = this.orderbooks.map((orderbook) => ({
+      type: "orderbook" as const,
+      orderbook,
+      address: orderbook.selfAddress,
+    }))
+
+    const clmmVenues: SplitVenue[] = this.clmmsWithTicks.map((clmmWithTicks) => ({
+      type: "clmm" as const,
+      clmmWithTicks,
+      address: clmmWithTicks.marketThree.selfAddress,
+    }))
+
+    return [...orderbookVenues, ...clmmVenues]
+  }
+
+  /**
+   * Gets the best quote from a single venue (used when only 1 venue or maxRoutes=1)
+   */
+  private getBestSingleVenueQuote(
+    venues: SplitVenue[],
+    direction: RouterQuoteDirection,
+    inAmount: number,
+    syExchangeRate: number,
+  ): SplitQuote | null {
+    let bestQuote: SplitQuote | null = null
+
+    for (const venue of venues) {
+      const quote = this.getVenueQuote(venue, direction, inAmount, syExchangeRate)
+      if (quote.outAmount <= 0) continue
+
+      const splitQuote: SplitQuote = {
+        totalOutAmount: quote.outAmount,
+        totalFees: quote.feesInOutToken,
+        routes: [
+          {
+            source: quote.source as RouterTradeSource.ORDERBOOK | RouterTradeSource.CLMM,
+            sourceAddress: quote.sourceAddress,
+            inAmount,
+            outAmount: quote.outAmount,
+            fees: quote.feesInOutToken,
+            percentage: 100,
+          },
+        ],
+      }
+
+      if (!bestQuote || splitQuote.totalOutAmount > bestQuote.totalOutAmount) {
+        bestQuote = splitQuote
+      }
+    }
+
+    return bestQuote
+  }
+
+  /**
+   * Gets a quote from a specific venue
+   */
+  private getVenueQuote(
+    venue: SplitVenue,
+    direction: RouterQuoteDirection,
+    inAmount: number,
+    syExchangeRate: number,
+  ): Quote {
+    if (venue.type === "orderbook") {
+      return this.getOrderbookQuote({
+        orderbook: venue.orderbook,
+        direction,
+        inAmount,
+        syExchangeRate,
+      })
+    }
+    return this.getClmmQuote({
+      clmmWithTicks: venue.clmmWithTicks,
+      direction,
+      inAmount,
+      syExchangeRate,
+    })
+  }
+
+  /**
+   * Optimizes the split allocation for a fixed set of venues using two-phase search:
+   * 1. Coarse grid search to find approximate optimum
+   * 2. Local refinement around the best coarse result
+   */
+  private optimizeSplitForVenues(
+    venues: SplitVenue[],
+    direction: RouterQuoteDirection,
+    totalInAmount: number,
+    syExchangeRate: number,
+    minSplitPercent: number,
+  ): SplitQuote | null {
+    const numVenues = venues.length
+
+    if (numVenues === 1) {
+      const quote = this.getVenueQuote(venues[0], direction, totalInAmount, syExchangeRate)
+      if (quote.outAmount <= 0) return null
+
+      return {
+        totalOutAmount: quote.outAmount,
+        totalFees: quote.feesInOutToken,
+        routes: [
+          {
+            source: quote.source as RouterTradeSource.ORDERBOOK | RouterTradeSource.CLMM,
+            sourceAddress: quote.sourceAddress,
+            inAmount: totalInAmount,
+            outAmount: quote.outAmount,
+            fees: quote.feesInOutToken,
+            percentage: 100,
+          },
+        ],
+      }
+    }
+
+    // Phase 1: Coarse grid search
+    const coarseSplits = generateSplitAllocations(numVenues, SPLIT_ROUTING_CONFIG.COARSE_STEP, minSplitPercent)
+    let bestCoarseSplit: number[] | null = null
+    let bestCoarseOutput = -1
+
+    for (const split of coarseSplits) {
+      const output = this.evaluateSplit(venues, split, direction, totalInAmount, syExchangeRate)
+      if (output > bestCoarseOutput) {
+        bestCoarseOutput = output
+        bestCoarseSplit = split
+      }
+    }
+
+    if (!bestCoarseSplit) return null
+
+    // Phase 2: Local refinement around best coarse result
+    const refinedSplits = generateRefinedSplits(
+      bestCoarseSplit,
+      SPLIT_ROUTING_CONFIG.REFINEMENT_RANGE,
+      SPLIT_ROUTING_CONFIG.FINE_STEP,
+      minSplitPercent,
+    )
+
+    let bestSplit = bestCoarseSplit
+    let bestOutput = bestCoarseOutput
+
+    for (const split of refinedSplits) {
+      const output = this.evaluateSplit(venues, split, direction, totalInAmount, syExchangeRate)
+      if (output > bestOutput) {
+        bestOutput = output
+        bestSplit = split
+      }
+    }
+
+    // Build the final SplitQuote result
+    return this.buildSplitQuote(venues, bestSplit, direction, totalInAmount, syExchangeRate)
+  }
+
+  /**
+   * Evaluates a split allocation and returns total output amount
+   * Used for fast comparison during optimization
+   */
+  private evaluateSplit(
+    venues: SplitVenue[],
+    splitPercents: number[],
+    direction: RouterQuoteDirection,
+    totalInAmount: number,
+    syExchangeRate: number,
+  ): number {
+    let totalOut = 0
+
+    for (let i = 0; i < venues.length; i++) {
+      const inAmount = (totalInAmount * splitPercents[i]) / 100
+      if (inAmount <= 0) continue
+
+      const quote = this.getVenueQuote(venues[i], direction, inAmount, syExchangeRate)
+      if (quote.outAmount <= 0) return -1 // Invalid split, venue can't handle this amount
+
+      totalOut += quote.outAmount
+    }
+
+    return totalOut
+  }
+
+  /**
+   * Builds the full SplitQuote result from a split allocation
+   */
+  private buildSplitQuote(
+    venues: SplitVenue[],
+    splitPercents: number[],
+    direction: RouterQuoteDirection,
+    totalInAmount: number,
+    syExchangeRate: number,
+  ): SplitQuote | null {
+    const routes: SplitRoute[] = []
+    let totalOutAmount = 0
+    let totalFees = 0
+
+    for (let i = 0; i < venues.length; i++) {
+      const percentage = splitPercents[i]
+      if (percentage <= 0) continue
+
+      const inAmount = (totalInAmount * percentage) / 100
+      const quote = this.getVenueQuote(venues[i], direction, inAmount, syExchangeRate)
+
+      if (quote.outAmount <= 0) return null
+
+      routes.push({
+        source: quote.source as RouterTradeSource.ORDERBOOK | RouterTradeSource.CLMM,
+        sourceAddress: quote.sourceAddress,
+        inAmount,
+        outAmount: quote.outAmount,
+        fees: quote.feesInOutToken,
+        percentage,
+      })
+
+      totalOutAmount += quote.outAmount
+      totalFees += quote.feesInOutToken
+    }
+
+    if (routes.length === 0) return null
+
+    return { totalOutAmount, totalFees, routes }
+  }
+
   static async fetchLegacyMarkets(
-    connection: web3.Connection,
+    connection: Connection,
     args: {
       env: Environment
       vault?: Vault
       legacyMarketsParams: {
-        address: web3.PublicKey
+        address: PublicKey
         options?: MarketLoadOptions
       }[]
     },
@@ -142,12 +432,12 @@ export class Router {
   }
 
   static async fetchOrderbooks(
-    connection: web3.Connection,
+    connection: Connection,
     args: {
       env: Environment
       vault?: Vault
       orderbookParams: {
-        address: web3.PublicKey
+        address: PublicKey
         options?: OrderbookLoadOptions
       }[]
     },
@@ -160,10 +450,10 @@ export class Router {
   }
 
   static async fetchClmmsWithTicks(
-    connection: web3.Connection,
-    clmmAddresses: web3.PublicKey[],
+    connection: Connection,
+    clmmAddresses: PublicKey[],
   ): Promise<{ marketThree: MarketThree; ticks: Ticks }[]> {
-    const fetchClmmWithTicks = async (marketThreeAddress: web3.PublicKey) => {
+    const fetchClmmWithTicks = async (marketThreeAddress: PublicKey) => {
       const xponFetcher = new ExponentFetcher({ connection })
       const marketThree = await xponFetcher.fetchMarketThree(marketThreeAddress)
       const ticks = await xponFetcher.fetchMarketThreeTicks(marketThree.ticks)
@@ -190,10 +480,19 @@ export class Router {
     }
 
     if (direction === RouterQuoteDirection.BASE_TO_PT) {
-      const ptOut = marketCalculator.estimateNetPtForExactNetAsset(inAmount)
-      const { feeAsset, netTraderPt } = marketCalculator.calcTradePt(ptOut, false)
+      // Negative inAmount indicates trader is spending asset (buying PT)
+      const ptOut = marketCalculator.estimateNetPtForExactNetAsset(-inAmount)
+      if (ptOut === null) {
+        return {
+          outAmount: 0,
+          feesInOutToken: 0,
+          source: RouterTradeSource.MARKET,
+          sourceAddress: market.selfAddress,
+        }
+      }
+      const { feeAsset } = marketCalculator.calcTradePt(ptOut, false)
       return {
-        outAmount: netTraderPt,
+        outAmount: ptOut,
         feesInOutToken: feeAsset,
         source: RouterTradeSource.MARKET,
         sourceAddress: market.selfAddress,
@@ -332,7 +631,7 @@ export type Quote = {
   outAmount: number
   feesInOutToken: number
   source: RouterTradeSource
-  sourceAddress: web3.PublicKey
+  sourceAddress: PublicKey
 }
 
 /**
@@ -358,3 +657,154 @@ export enum RouterQuoteDirection {
   YT_TO_BASE,
   PT_TO_BASE,
 }
+
+// ============================================================================
+// Split Routing Types
+// ============================================================================
+
+/** A single route in a split quote */
+export type SplitRoute = {
+  source: RouterTradeSource.ORDERBOOK | RouterTradeSource.CLMM
+  sourceAddress: PublicKey
+  inAmount: number
+  outAmount: number
+  fees: number
+  percentage: number
+}
+
+/** Result of split routing optimization */
+export type SplitQuote = {
+  totalOutAmount: number
+  totalFees: number
+  routes: SplitRoute[]
+}
+
+/** Internal venue representation for split routing */
+type SplitVenue =
+  | { type: "orderbook"; orderbook: Orderbook; address: PublicKey }
+  | { type: "clmm"; clmmWithTicks: ClmmWithTicks; address: PublicKey }
+
+// ============================================================================
+// Combinatorics Utilities
+// ============================================================================
+
+/**
+ * Generates all k-combinations of indices [0, n)
+ * Uses iterative approach for efficiency
+ */
+function generateCombinations(n: number, k: number): number[][] {
+  if (k > n || k <= 0) return []
+  if (k === n) return [Array.from({ length: n }, (_, i) => i)]
+
+  const result: number[][] = []
+  const combination = Array.from({ length: k }, (_, i) => i)
+
+  while (true) {
+    result.push([...combination])
+
+    // Find rightmost element that can be incremented
+    let i = k - 1
+    while (i >= 0 && combination[i] === n - k + i) {
+      i--
+    }
+
+    if (i < 0) break
+
+    // Increment and reset elements to the right
+    combination[i]++
+    for (let j = i + 1; j < k; j++) {
+      combination[j] = combination[j - 1] + 1
+    }
+  }
+
+  return result
+}
+
+/**
+ * Generates all valid split allocations for n venues with given step size
+ * Each allocation sums to 100 and respects minimum allocation
+ */
+function generateSplitAllocations(numVenues: number, stepSize: number, minPercent: number): number[][] {
+  const allocations: number[][] = []
+
+  if (numVenues === 2) {
+    // Optimized path for 2 venues
+    for (let a = minPercent; a <= 100 - minPercent; a += stepSize) {
+      allocations.push([a, 100 - a])
+    }
+    return allocations
+  }
+
+  if (numVenues === 3) {
+    // Optimized path for 3 venues
+    for (let a = minPercent; a <= 100 - 2 * minPercent; a += stepSize) {
+      for (let b = minPercent; b <= 100 - a - minPercent; b += stepSize) {
+        const c = 100 - a - b
+        if (c >= minPercent) {
+          allocations.push([a, b, c])
+        }
+      }
+    }
+    return allocations
+  }
+
+  // Generic recursive case (shouldn't be needed with MAX_ROUTES=3)
+  const generate = (remaining: number, depth: number, current: number[]): void => {
+    if (depth === numVenues - 1) {
+      if (remaining >= minPercent) {
+        allocations.push([...current, remaining])
+      }
+      return
+    }
+
+    const maxForThis = remaining - minPercent * (numVenues - depth - 1)
+    for (let val = minPercent; val <= maxForThis; val += stepSize) {
+      current.push(val)
+      generate(remaining - val, depth + 1, current)
+      current.pop()
+    }
+  }
+
+  generate(100, 0, [])
+  return allocations
+}
+
+/**
+ * Generates refined split allocations around a center point
+ * Used for local optimization after coarse search
+ */
+function generateRefinedSplits(center: number[], range: number, stepSize: number, minPercent: number): number[][] {
+  const numVenues = center.length
+  const refinedSplits: number[][] = []
+
+  if (numVenues === 2) {
+    const centerA = center[0]
+    const minA = Math.max(minPercent, centerA - range)
+    const maxA = Math.min(100 - minPercent, centerA + range)
+
+    for (let a = minA; a <= maxA; a += stepSize) {
+      refinedSplits.push([a, 100 - a])
+    }
+    return refinedSplits
+  }
+
+  if (numVenues === 3) {
+    const [centerA, centerB] = center
+
+    for (let da = -range; da <= range; da += stepSize) {
+      for (let db = -range; db <= range; db += stepSize) {
+        const a = centerA + da
+        const b = centerB + db
+        const c = 100 - a - b
+
+        if (a >= minPercent && b >= minPercent && c >= minPercent) {
+          refinedSplits.push([a, b, c])
+        }
+      }
+    }
+    return refinedSplits
+  }
+
+  // Fallback: just return the center for unsupported venue counts
+  return [center]
+}