@luxexchange/lx 1.0.0

package/src/features/transactions/swap/plan/planWatcherSaga.ts

@@ -0,0 +1,150 @@
+import { FeatureFlags, getFeatureFlag, getStatsigClient } from '@luxexchange/gating'
+import { call, delay, fork, select } from 'typed-redux-saga'
+import { makeSelectPlanTransaction } from '@luxexchange/lx/src/features/transactions/selectors'
+import {
+  logPlanPollDebug,
+  PLAN_MAX_AGE_MS,
+  PLAN_POLLING_INITIAL_DELAY_MS,
+  PLAN_POLLING_INTERVAL_MS,
+  pollPlanStatus,
+  shouldPollPlan,
+} from '@luxexchange/lx/src/features/transactions/swap/plan/planPollingUtils'
+import { PlanTransactionDetails } from '@luxexchange/lx/src/features/transactions/types/transactionDetails'
+import { logger } from '@luxfi/utilities/src/logger/logger'
+import { ONE_SECOND_MS } from '@luxfi/utilities/src/time/time'
+
+interface PlanListener {
+  updatePlanStatus: (updatedPlan: PlanTransactionDetails) => void
+  promise: Promise<PlanTransactionDetails>
+  timeoutId: NodeJS.Timeout
+}
+
+export class PlanWatcher {
+  private static listeners: { [planId: string]: PlanListener } = {}
+
+  /**
+   * There is an issue on extension where the sagas are initialized multiple times.
+   * The first instance of this polling utility will not have access to the latest store.
+   * As a temporary fix, we can use an index to track & cancel the previous instance of the polling utility.
+   */
+  private static index = 0
+
+  static *initialize(): Generator<unknown> {
+    yield* call(PlanWatcher.waitForStatsigReady)
+    if (!getFeatureFlag(FeatureFlags.ChainedActions)) {
+      return
+    }
+    PlanWatcher.index++
+    yield* fork(PlanWatcher.poll, PlanWatcher.index)
+  }
+
+  private static *waitForStatsigReady(): Generator<unknown> {
+    while (getStatsigClient().loadingStatus !== 'Ready') {
+      yield* delay(ONE_SECOND_MS)
+    }
+  }
+
+  private static *poll(index: number): Generator<unknown> {
+    if (index !== PlanWatcher.index) {
+      return
+    }
+    yield* delay(PLAN_POLLING_INITIAL_DELAY_MS)
+
+    try {
+      const planIds = Object.keys(PlanWatcher.listeners)
+      if (!planIds.length) {
+        yield* fork(PlanWatcher.poll, index)
+        return
+      }
+
+      for (const planId of planIds) {
+        yield* call(PlanWatcher.processPlanPoll, planId)
+      }
+    } catch (error) {
+      logger.error(error, {
+        tags: {
+          file: 'planWatcherSaga',
+          function: 'poll',
+        },
+      })
+    }
+    yield* delay(PLAN_POLLING_INTERVAL_MS)
+    yield* fork(PlanWatcher.poll, index)
+  }
+
+  private static cleanupListener(planId: string): void {
+    logPlanPollDebug({
+      functionName: 'cleanupListener',
+      message: 'Cleaning up listener',
+      extras: { planId },
+    })
+    const listener = PlanWatcher.listeners[planId]
+    if (listener) {
+      clearTimeout(listener.timeoutId)
+      delete PlanWatcher.listeners[planId]
+    }
+  }
+
+  private static *processPlanPoll(planId: string): Generator<unknown> {
+    logPlanPollDebug({
+      functionName: 'processPlanPoll',
+      message: 'Processing plan poll',
+      extras: { planId },
+    })
+    const selectPlanTransaction = yield* call(makeSelectPlanTransaction)
+    const localPlan = yield* select(selectPlanTransaction, { planId })
+    if (!localPlan) {
+      PlanWatcher.cleanupListener(planId)
+      return
+    }
+
+    if (!shouldPollPlan(localPlan)) {
+      PlanWatcher.listeners[planId]?.updatePlanStatus(localPlan)
+      PlanWatcher.cleanupListener(planId)
+      return
+    }
+
+    const result = yield* call(pollPlanStatus, localPlan)
+
+    if (result.updatedPlan) {
+      PlanWatcher.listeners[planId]?.updatePlanStatus(result.updatedPlan)
+      PlanWatcher.cleanupListener(planId)
+    } else if (result.shouldRemoveFromWatchList) {
+      PlanWatcher.listeners[planId]?.updatePlanStatus(localPlan)
+      PlanWatcher.cleanupListener(planId)
+    }
+  }
+
+  static *waitForPlanStatus(planId: string) {
+    logPlanPollDebug({
+      fileName: 'planWatcherSaga',
+      functionName: 'waitForPlanStatus',
+      message: 'Waiting for plan status',
+      extras: { planId },
+    })
+    const existingListenerPromise = PlanWatcher.listeners[planId]?.promise
+    if (existingListenerPromise) {
+      return yield* call(() => existingListenerPromise)
+    }
+
+    let resolvePromise: (value: PlanTransactionDetails) => void
+    const promise = new Promise<PlanTransactionDetails>((resolve) => {
+      resolvePromise = resolve
+    })
+
+    const timeoutId = setTimeout(() => {
+      const listener = PlanWatcher.listeners[planId]
+      if (listener) {
+        logger.warn('planWatcherSaga', 'waitForPlanStatus', 'Plan listener timed out', { planId })
+        // Resolve with undefined to unblock the caller - they should handle this case
+        // biome-ignore lint/suspicious/noExplicitAny: Resolving with undefined to signal timeout
+        resolvePromise(undefined as any)
+        delete PlanWatcher.listeners[planId]
+      }
+    }, PLAN_MAX_AGE_MS)
+
+    // biome-ignore lint/style/noNonNullAssertion: Must appease typechecker since resolvePromise is assigned inside promise scope
+    PlanWatcher.listeners[planId] = { updatePlanStatus: resolvePromise!, promise, timeoutId }
+    return yield* call(() => promise)
+  }
+}

package/src/features/transactions/swap/plan/prefetchedPlanStore.ts

@@ -0,0 +1,86 @@
+import { TradingApi } from '@luxexchange/api'
+import { PlanResponse } from '@luxexchange/api/src/clients/trading/__generated__/models/PlanResponse'
+import { TradingApiSessionClient } from '@luxexchange/lx/src/data/apiClients/tradingApi/TradingApiSessionClient'
+import { Trade } from '@luxexchange/lx/src/features/transactions/swap/types/trade'
+import { isChained } from '@luxexchange/lx/src/features/transactions/swap/utils/routing'
+import { requireAcceptNewTrade } from '@luxexchange/lx/src/features/transactions/swap/utils/trade'
+import { logger } from '@luxfi/utilities/src/logger/logger'
+import { ONE_SECOND_MS } from '@luxfi/utilities/src/time/time'
+
+const PREFETCH_TTL_MS = 15 * ONE_SECOND_MS
+
+interface PrefetchedPlan {
+  promise: Promise<PlanResponse>
+  trade: Trade
+}
+
+let prefetched: PrefetchedPlan | null = null
+let expiryTimer: ReturnType<typeof setTimeout> | null = null
+
+export function prefetchPlan(trade: Trade, walletExecutionContext?: TradingApi.WalletExecutionContext): void {
+  if (!isChained(trade)) {
+    return
+  }
+
+  // Clear any prior prefetch
+  clearPrefetchedPlan()
+
+  const promise = TradingApiSessionClient.createNewPlan({
+    quote: trade.quote.quote,
+    // @ts-expect-error - CHAINED is the only supported but doesn't satisfy input param type for some reason
+    routing: trade.quote.routing,
+    walletExecutionContext,
+  })
+
+  prefetched = { promise, trade }
+
+  // Auto-invalidate after TTL so stale plans are never consumed
+  expiryTimer = setTimeout(() => {
+    if (prefetched?.promise === promise) {
+      prefetched = null
+    }
+    expiryTimer = null
+  }, PREFETCH_TTL_MS)
+
+  // Fire-and-forget: log + clear on error
+  promise.catch((error) => {
+    logger.warn('prefetchedPlanStore', 'prefetchPlan', 'Prefetch failed, will fall back to normal plan creation', {
+      error: error instanceof Error ? error.message : String(error),
+    })
+    // Only clear if this is still the active prefetch
+    if (prefetched?.promise === promise) {
+      prefetched = null
+    }
+  })
+}
+
+export async function consumePrefetchedPlan(currentTrade: Trade): Promise<PlanResponse | null> {
+  // One-shot: grab and null out immediately
+  const current = prefetched
+  prefetched = null
+
+  if (!current) {
+    return null
+  }
+
+  // Trade drifted since prefetch — discard
+  if (requireAcceptNewTrade(current.trade, currentTrade)) {
+    logger.info('prefetchedPlanStore', 'consumePrefetchedPlan', 'Trade drifted since prefetch, discarding')
+    return null
+  }
+
+  try {
+    return await current.promise
+  } catch {
+    // Prefetch failed — caller will fall through to normal plan creation
+    return null
+  }
+}
+
+export function clearPrefetchedPlan(): void {
+  prefetched = null
+  if (expiryTimer) {
+    clearTimeout(expiryTimer)
+    expiryTimer = null
+  }
+}

package/src/features/transactions/swap/plan/priceChangeDetection.test.ts

@@ -0,0 +1,146 @@
+import { CurrencyAmount } from '@uniswap/sdk-core'
+import { TradingApi } from '@luxexchange/api'
+import { UNI, WBTC } from '@luxexchange/lx/src/constants/tokens'
+import { UniverseChainId } from '@luxexchange/lx/src/features/chains/types'
+import { buildTradeFromPlanResponse } from '@luxexchange/lx/src/features/transactions/swap/plan/planSagaUtils'
+import { ChainedActionTrade } from '@luxexchange/lx/src/features/transactions/swap/types/trade'
+import { requireAcceptNewTrade } from '@luxexchange/lx/src/features/transactions/swap/utils/trade'
+
+const INPUT_TOKEN = UNI[UniverseChainId.Mainnet]
+const OUTPUT_TOKEN = WBTC
+
+const INPUT_AMOUNT = '1000000000000000000' // 1e18
+const OUTPUT_AMOUNT = '100000000' // 1e8
+
+function createMockTruncatedStep(slippage = 0.5): TradingApi.TruncatedPlanStep {
+  return {
+    stepType: TradingApi.PlanStepType.CLASSIC,
+    slippage,
+  }
+}
+
+function createMockPlanStep(slippage = 0.5): TradingApi.PlanStep {
+  return {
+    stepIndex: 0,
+    stepType: TradingApi.PlanStepType.CLASSIC,
+    status: TradingApi.PlanStepStatus.AWAITING_ACTION,
+    method: TradingApi.PlanStepMethod.SEND_TX,
+    payload: {},
+    slippage,
+  } as TradingApi.PlanStep
+}
+
+function createChainedTrade(outputAmount: string): ChainedActionTrade {
+  return new ChainedActionTrade({
+    quote: {
+      routing: TradingApi.Routing.CHAINED,
+      requestId: 'test-request',
+      permitData: null,
+      quote: {
+        input: { amount: INPUT_AMOUNT, token: INPUT_TOKEN.address },
+        output: { amount: outputAmount, token: OUTPUT_TOKEN.address, recipient: '0xrecipient' },
+        swapper: '0xswapper',
+        tokenInChainId: UniverseChainId.Mainnet as unknown as TradingApi.ChainId,
+        tokenOutChainId: UniverseChainId.Mainnet as unknown as TradingApi.ChainId,
+        tradeType: TradingApi.TradeType.EXACT_INPUT,
+        slippage: 0.5,
+        quoteId: 'test-quote',
+        gasFee: '0',
+        gasFeeUSD: '0',
+        gasFeeQuote: '0',
+        gasUseEstimate: '0',
+        gasStrategies: [],
+        steps: [createMockTruncatedStep()],
+      },
+    },
+    currencyIn: INPUT_TOKEN,
+    currencyOut: OUTPUT_TOKEN,
+  })
+}
+
+function createPlanResponse(expectedOutput: string): TradingApi.PlanResponse {
+  return {
+    planId: 'test-plan',
+    requestId: 'test-request',
+    quoteId: 'test-quote',
+    expectedOutput,
+    swapper: '0xswapper',
+    recipient: '0xrecipient',
+    gasFee: '0',
+    gasFeeUSD: '0',
+    gasFeeQuote: '0',
+    gasUseEstimate: '0',
+    gasStrategies: [],
+    timeEstimateMs: 10000,
+    status: TradingApi.PlanStatus.ACTIVE,
+    currentStepIndex: 0,
+    steps: [createMockPlanStep()],
+  } as TradingApi.PlanResponse
+}
+
+/** Computes a percentage of OUTPUT_AMOUNT using integer math */
+function scaleOutput(numerator: number, denominator: number): string {
+  const base = Number(OUTPUT_AMOUNT)
+  return String(Math.floor((base * numerator) / denominator))
+}
+
+describe('plan price change detection', () => {
+  const address = '0x1234567890123456789012345678901234567890' as Address
+
+  it('does not interrupt when expectedOutput equals original', () => {
+    const originalTrade = createChainedTrade(OUTPUT_AMOUNT)
+    const planResponse = createPlanResponse(OUTPUT_AMOUNT)
+    const refreshedTrade = buildTradeFromPlanResponse({ originalTrade, planResponse, address })
+
+    expect(requireAcceptNewTrade(originalTrade, refreshedTrade)).toBe(false)
+  })
+
+  it('does not interrupt when expectedOutput improves (higher)', () => {
+    const originalTrade = createChainedTrade(OUTPUT_AMOUNT)
+    // 5% improvement
+    const improvedOutput = scaleOutput(105, 100)
+    const planResponse = createPlanResponse(improvedOutput)
+    const refreshedTrade = buildTradeFromPlanResponse({ originalTrade, planResponse, address })
+
+    expect(requireAcceptNewTrade(originalTrade, refreshedTrade)).toBe(false)
+  })
+
+  it('does not interrupt when drop is within 1% threshold', () => {
+    const originalTrade = createChainedTrade(OUTPUT_AMOUNT)
+    // 0.5% drop — within the 1% threshold
+    const slightDrop = scaleOutput(995, 1000)
+    const planResponse = createPlanResponse(slightDrop)
+    const refreshedTrade = buildTradeFromPlanResponse({ originalTrade, planResponse, address })
+
+    expect(requireAcceptNewTrade(originalTrade, refreshedTrade)).toBe(false)
+  })
+
+  it('interrupts when expectedOutput drops more than 1%', () => {
+    const originalTrade = createChainedTrade(OUTPUT_AMOUNT)
+    // 2% drop — beyond the 1% threshold
+    const bigDrop = scaleOutput(98, 100)
+    const planResponse = createPlanResponse(bigDrop)
+    const refreshedTrade = buildTradeFromPlanResponse({ originalTrade, planResponse, address })
+
+    expect(requireAcceptNewTrade(originalTrade, refreshedTrade)).toBe(true)
+  })
+
+  it('preserves currency information in the refreshed trade', () => {
+    const originalTrade = createChainedTrade(OUTPUT_AMOUNT)
+    const planResponse = createPlanResponse(OUTPUT_AMOUNT)
+    const refreshedTrade = buildTradeFromPlanResponse({ originalTrade, planResponse, address })
+
+    expect(refreshedTrade.inputAmount.currency.equals(originalTrade.inputAmount.currency)).toBe(true)
+    expect(refreshedTrade.outputAmount.currency.equals(originalTrade.outputAmount.currency)).toBe(true)
+    expect(refreshedTrade.inputAmount.equalTo(originalTrade.inputAmount)).toBe(true)
+  })
+
+  it('correctly constructs output amount from plan response', () => {
+    const originalTrade = createChainedTrade(OUTPUT_AMOUNT)
+    const newOutput = '200000000'
+    const planResponse = createPlanResponse(newOutput)
+    const refreshedTrade = buildTradeFromPlanResponse({ originalTrade, planResponse, address })
+
+    expect(refreshedTrade.outputAmount.equalTo(CurrencyAmount.fromRawAmount(OUTPUT_TOKEN, newOutput))).toBe(true)
+  })
+})

package/src/features/transactions/swap/plan/slippage.test.ts

@@ -0,0 +1,124 @@
+import { TradingApi } from '@luxexchange/api'
+import {
+  calculatePlanCompoundSlippage,
+  getPlanCompoundSlippageTolerance,
+} from '@luxexchange/lx/src/features/transactions/swap/plan/slippage'
+
+describe('slippage', () => {
+  describe('calculatePlanCompoundSlippage', () => {
+    it('returns undefined for empty array', () => {
+      expect(calculatePlanCompoundSlippage([])).toBeUndefined()
+    })
+
+    it('returns single value unchanged', () => {
+      expect(calculatePlanCompoundSlippage([0.5])).toBe(0.5)
+      expect(calculatePlanCompoundSlippage([1.0])).toBe(1.0)
+      expect(calculatePlanCompoundSlippage([0])).toBe(0)
+    })
+
+    it('calculates compound slippage for two values', () => {
+      // 0.5% and 0.25%: 1 - (0.995 * 0.9975) = 1 - 0.9925125 = 0.0074875 = 0.74875%
+      const result = calculatePlanCompoundSlippage([0.5, 0.25])
+      expect(result).toBeCloseTo(0.74875, 5)
+    })
+
+    it('calculates compound slippage for three values', () => {
+      // 0.5%, 0.5%, 0.5%: 1 - (0.995^3) = 1 - 0.985074875 = 1.4925125%
+      const result = calculatePlanCompoundSlippage([0.5, 0.5, 0.5])
+      expect(result).toBeCloseTo(1.492512, 5)
+    })
+
+    it('handles zero slippage values', () => {
+      // 0% and 0.5%: 1 - (1 * 0.995) = 0.5%
+      expect(calculatePlanCompoundSlippage([0, 0.5])).toBeCloseTo(0.5, 5)
+      expect(calculatePlanCompoundSlippage([0, 0])).toBe(0)
+    })
+
+    it('handles high slippage values', () => {
+      // 5% and 5%: 1 - (0.95 * 0.95) = 1 - 0.9025 = 9.75%
+      const result = calculatePlanCompoundSlippage([5, 5])
+      expect(result).toBeCloseTo(9.75, 5)
+    })
+
+    it('handles floating-point precision correctly', () => {
+      // Multiple small values should not accumulate precision errors
+      const result = calculatePlanCompoundSlippage([0.1, 0.1, 0.1, 0.1, 0.1])
+      // 1 - (0.999)^5 = 0.499001...%
+      expect(result).toBeDefined()
+      expect(typeof result).toBe('number')
+      // Should be rounded to 6 decimal places
+      expect(result!.toString().split('.')[1]?.length ?? 0).toBeLessThanOrEqual(6)
+    })
+  })
+
+  describe('getPlanCompoundSlippageTolerance', () => {
+    const createMockStep = (stepType: TradingApi.PlanStepType, slippage?: number): TradingApi.PlanStep => {
+      const step = {
+        stepIndex: 0,
+        stepType,
+        status: TradingApi.PlanStepStatus.AWAITING_ACTION,
+        method: TradingApi.PlanStepMethod.SEND_TX,
+        payload: {},
+      } as TradingApi.PlanStep
+
+      if (slippage !== undefined) {
+        step.slippage = slippage
+      }
+
+      return step
+    }
+
+    it('returns undefined for undefined steps', () => {
+      expect(getPlanCompoundSlippageTolerance(undefined)).toBeUndefined()
+    })
+
+    it('returns undefined for empty steps', () => {
+      expect(getPlanCompoundSlippageTolerance([])).toBeUndefined()
+    })
+
+    it('returns undefined when no steps have slippage', () => {
+      const steps = [createMockStep(TradingApi.PlanStepType.BRIDGE), createMockStep(TradingApi.PlanStepType.WRAP)]
+      expect(getPlanCompoundSlippageTolerance(steps)).toBeUndefined()
+    })
+
+    it('returns single slippage unchanged', () => {
+      const steps = [createMockStep(TradingApi.PlanStepType.CLASSIC, 0.5)]
+      expect(getPlanCompoundSlippageTolerance(steps)).toBe(0.5)
+    })
+
+    it('calculates compound slippage for multiple swap steps', () => {
+      const steps = [
+        createMockStep(TradingApi.PlanStepType.CLASSIC, 0.5),
+        createMockStep(TradingApi.PlanStepType.CLASSIC, 0.25),
+      ]
+      const result = getPlanCompoundSlippageTolerance(steps)
+      // 1 - (0.995 * 0.9975) = 0.74875%
+      expect(result).toBeCloseTo(0.74875, 5)
+    })
+
+    it('skips steps without slippage in compound calculation', () => {
+      const steps = [
+        createMockStep(TradingApi.PlanStepType.CLASSIC, 0.5),
+        createMockStep(TradingApi.PlanStepType.BRIDGE), // No slippage
+        createMockStep(TradingApi.PlanStepType.CLASSIC, 0.25),
+      ]
+      const result = getPlanCompoundSlippageTolerance(steps)
+      // Should only compound 0.5% and 0.25%, ignoring BRIDGE
+      // 1 - (0.995 * 0.9975) = 0.74875%
+      expect(result).toBeCloseTo(0.74875, 5)
+    })
+
+    it('handles real-world chained action scenario', () => {
+      // Typical cross-chain swap: CLASSIC -> BRIDGE -> CLASSIC
+      const steps = [
+        createMockStep(TradingApi.PlanStepType.APPROVAL_TXN), // No slippage
+        createMockStep(TradingApi.PlanStepType.CLASSIC, 0.5),
+        createMockStep(TradingApi.PlanStepType.BRIDGE), // No slippage
+        createMockStep(TradingApi.PlanStepType.CLASSIC, 0.25),
+      ]
+      const result = getPlanCompoundSlippageTolerance(steps)
+      // Should compound 0.5% and 0.25%
+      expect(result).toBeCloseTo(0.74875, 5)
+    })
+  })
+})

package/src/features/transactions/swap/plan/slippage.ts

@@ -0,0 +1,36 @@
+import { TradingApi } from '@luxexchange/api'
+
+/**
+ * Calculates compound slippage from individual step slippages.
+ * Formula: compoundSlippage = 1 - ((1-s1) × (1-s2) × ... × (1-sn))
+ *
+ * @param slippages - Array of slippage percentages (e.g., 0.5 for 0.5%)
+ * @returns Compound slippage percentage, or undefined if empty
+ */
+export function calculatePlanCompoundSlippage(slippages: number[]): number | undefined {
+  if (slippages.length === 0) {
+    return undefined
+  }
+  if (slippages.length === 1) {
+    return slippages[0]
+  }
+
+  const compoundFactor = slippages.reduce((acc, slip) => acc * (1 - slip / 100), 1)
+  const compound = (1 - compoundFactor) * 100
+  return Math.round(compound * 1_000_000) / 1_000_000
+}
+
+/**
+ * Gets compound slippage tolerance for a chained action plan.
+ */
+export function getPlanCompoundSlippageTolerance(
+  steps?: Array<TradingApi.PlanStep | TradingApi.TruncatedPlanStep>,
+): number | undefined {
+  if (!steps) {
+    return undefined
+  }
+
+  const slippageValues = steps.map((step) => step.slippage).filter((s): s is number => s !== undefined)
+
+  return calculatePlanCompoundSlippage(slippageValues)
+}