feat(swapper): per-swapper quote deadlines, honored by the api quote store

packages/public-api/docs/rest-api-guide.md

@@ -44,7 +44,7 @@ X-Partner-Code: your-partner-code
 - `swapperName` comes from the rate you chose in step 2.
 - `slippageTolerancePercentageDecimal` is optional; `accountNumber` is optional (defaults to `0`) and is needed for chains that derive addresses per account index (e.g. UTXO/Cosmos).
 - The response includes a `quoteId` (needed for status tracking), an `approval` object (whether an ERC-20 approval is required, the spender, and ready-to-sign `approvalTxs` when it is), and a `steps` array. Each step may include `transactionData` — a discriminated union on `type` (`evm`, `solana`, `utxo`, `cosmossdk_msg_send`, `cosmossdk_msg_deposit`) — describing exactly what to sign for that chain.
-- Quotes expire: honor the `expiresAt` timestamp (≈ 60s after issue). Request a fresh quote rather than submitting an expired one.
+- Quotes expire: honor the `expiresAt` timestamp — it reflects the swapper's own quote deadline (e.g. THORChain inbound addresses rotate, deposit-address swappers deactivate their channels; deadline-less providers get a conservative 60s). **Never sign or broadcast after `expiresAt`** — for deposit-style swappers funds sent late can be lost. Request a fresh quote instead.
 
 ## 4. Execute the swap
 

packages/public-api/src/constants.ts

@@ -54,3 +54,7 @@ export const ENABLED_SWAPPER_NAMES: readonly SwapperName[] = [
   SwapperName.Thorchain,
   SwapperName.Zrx,
 ]
+
+// Sanity ceiling catching provider deadline bugs (unit inflation, sentinel far-future dates).
+// Widest legitimate deadline today is chainflip's 6h - raise this if a swapper ever quotes longer.
+export const MAX_QUOTE_DEADLINE_MS = 7 * 24 * 60 * 60 * 1000

packages/public-api/src/lib/quoteStore.test.ts

@@ -3,6 +3,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { StoredQuote } from './quoteStore'
 import { QuoteStore } from './quoteStore'
 
+// The store treats expiresAt as caller-provided data (swapper deadline + bind grace in prod)
+const QUOTE_TTL_MS = 15 * 60 * 1000
+
 const makeQuote = (overrides: Partial<StoredQuote> = {}): StoredQuote => ({
   quoteId: 'quote-1',
   swapperName: '0x',
@@ -18,7 +21,7 @@ const makeQuote = (overrides: Partial<StoredQuote> = {}): StoredQuote => ({
   sendAddress: '0xsender',
   rate: '1800',
   createdAt: Date.now(),
-  expiresAt: Date.now() + QuoteStore.QUOTE_TTL_MS,
+  expiresAt: Date.now() + QUOTE_TTL_MS,
   metadata: {
     stepIndex: 0,
     quoteId: 'quote-1',
@@ -56,14 +59,14 @@ describe('QuoteStore', () => {
     it('returns quote within QUOTE_TTL_MS', () => {
       const quote = makeQuote()
       store.set(quote.quoteId, quote)
-      vi.advanceTimersByTime(QuoteStore.QUOTE_TTL_MS - 1)
+      vi.advanceTimersByTime(QUOTE_TTL_MS - 1)
       expect(store.get(quote.quoteId)).toBeDefined()
     })
 
     it('expires quote after QUOTE_TTL_MS', () => {
       const quote = makeQuote()
       store.set(quote.quoteId, quote)
-      vi.advanceTimersByTime(QuoteStore.QUOTE_TTL_MS + 1)
+      vi.advanceTimersByTime(QUOTE_TTL_MS + 1)
       expect(store.get(quote.quoteId)).toBeUndefined()
     })
   })
@@ -74,13 +77,13 @@ describe('QuoteStore', () => {
       const quote = makeQuote({
         txHash: '0xabc',
         registeredAt: now,
-        expiresAt: now + QuoteStore.QUOTE_TTL_MS,
+        expiresAt: now + QUOTE_TTL_MS,
         status: 'submitted',
       })
       store.set(quote.quoteId, quote)
 
       // past QUOTE_TTL but within EXECUTION_TTL
-      vi.advanceTimersByTime(QuoteStore.QUOTE_TTL_MS + 1)
+      vi.advanceTimersByTime(QUOTE_TTL_MS + 1)
       expect(store.get(quote.quoteId)).toBeDefined()
     })
 
@@ -158,7 +161,7 @@ describe('QuoteStore', () => {
       store.set(quote.quoteId, quote)
       expect(store.size()).toBe(1)
 
-      vi.advanceTimersByTime(QuoteStore.QUOTE_TTL_MS + QuoteStore.CLEANUP_INTERVAL_MS + 1)
+      vi.advanceTimersByTime(QUOTE_TTL_MS + QuoteStore.CLEANUP_INTERVAL_MS + 1)
 
       expect(store.size()).toBe(0)
     })

packages/public-api/src/lib/quoteStore.ts

@@ -25,8 +25,8 @@ export type StoredQuote = {
 
 /**
  * In-memory quote store with dual TTL:
- * - 15 minutes for unsubmitted quotes (quote validity window)
- * - 60 minutes after txHash is bound (execution tracking window)
+ * - unsubmitted: swapper deadline + bind grace (a slow first confirmation must still bind)
+ * - submitted: txHash bind time + execution TTL (destination-chain settlement tracking)
  *
  * Automatic sweep of expired entries every 60 seconds.
  * Migration path: swap to Redis with zero code changes (same get/set/delete interface).
@@ -36,7 +36,7 @@ export class QuoteStore {
   private txHashIndex = new Map<string, string>()
   private cleanupInterval: ReturnType<typeof setInterval>
 
-  static readonly QUOTE_TTL_MS = 15 * 60 * 1000
+  static readonly BIND_GRACE_MS = 60 * 60 * 1000
   static readonly EXECUTION_TTL_MS = 60 * 60 * 1000
   static readonly CLEANUP_INTERVAL_MS = 60 * 1000
   static readonly MAX_QUOTES = 10000

packages/public-api/src/routes/quote/getQuote.ts

@@ -12,7 +12,7 @@ import type { Request, Response } from 'express'
 import { v4 as uuidv4 } from 'uuid'
 
 import { getAsset } from '../../assets'
-import { ENABLED_SWAPPER_NAMES } from '../../constants'
+import { ENABLED_SWAPPER_NAMES, MAX_QUOTE_DEADLINE_MS } from '../../constants'
 import { env } from '../../env'
 import { QuoteStore, quoteStore } from '../../lib/quoteStore'
 import { registry } from '../../registry'
@@ -48,6 +48,7 @@ registry.registerPath({
     404: { description: 'No quote available' },
     429: rateLimitResponse,
     500: { description: 'Internal server error' },
+    502: { description: 'Swapper returned an expired or implausible quote deadline' },
   },
 })
 
@@ -184,6 +185,23 @@ export const getQuote = async (req: Request, res: Response): Promise<void> => {
       rate: quote.rate,
     }
 
+    if (!Number.isFinite(quote.deadline) || quote.deadline <= now) {
+      res.status(502).json({
+        error: 'Swapper quote expired before it could be returned; request a new quote',
+      } satisfies ErrorResponse)
+      return
+    }
+
+    if (quote.deadline > now + MAX_QUOTE_DEADLINE_MS) {
+      console.error(
+        `[getQuote] ${validSwapperName} deadline ${quote.deadline} exceeds MAX_QUOTE_DEADLINE_MS sanity ceiling - provider bug, or raise the ceiling if this swapper legitimately quotes longer`,
+      )
+      res.status(502).json({
+        error: `Swapper quote deadline exceeds the MAX_QUOTE_DEADLINE_MS sanity ceiling`,
+      } satisfies ErrorResponse)
+      return
+    }
+
     quoteStore.set(quoteId, {
       ...baseQuote,
       sellAssetId: sellAsset.assetId,
@@ -193,7 +211,7 @@ export const getQuote = async (req: Request, res: Response): Promise<void> => {
       partnerAddress: req.affiliateInfo?.partnerAddress,
       partnerCode: req.affiliateInfo?.partnerCode,
       createdAt: now,
-      expiresAt: now + QuoteStore.QUOTE_TTL_MS,
+      expiresAt: quote.deadline + QuoteStore.BIND_GRACE_MS,
       metadata: buildSwapMetadata(step, { stepIndex: 0, quoteId }),
       status: 'pending',
     })
@@ -207,7 +225,7 @@ export const getQuote = async (req: Request, res: Response): Promise<void> => {
       networkFeeCryptoBaseUnit: step.feeData.networkFeeCryptoBaseUnit,
       steps: quote.steps.map(transformQuoteStep),
       approval: await buildApprovalInfo(step, sendAddress),
-      expiresAt: now + 60_000,
+      expiresAt: quote.deadline,
     }
 
     res.json(response)

packages/public-api/src/routes/quote/types.ts

@@ -154,7 +154,11 @@ export const QuoteResponseSchema = registry.register(
     networkFeeCryptoBaseUnit: z.string().optional().openapi({ example: '23000' }),
     approval: ApprovalInfoSchema,
     steps: z.array(QuoteStepSchema),
-    expiresAt: z.number(),
+    expiresAt: z.number().openapi({
+      example: 1754265600000,
+      description:
+        "Epoch ms after which the quote must not be executed - the swapper's own deadline (inbound address rotation, deposit channel expiry, order validity). Broadcasting after it risks failed swaps or, for deposit-style swappers, lost funds. Request a fresh quote instead.",
+    }),
   }),
 )
 

packages/swapper/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/swapper",
-  "version": "18.1.1",
+  "version": "19.0.0",
   "repository": "https://github.com/shapeshift/web",
   "license": "MIT",
   "type": "module",

packages/swapper/src/swappers/AcrossSwapper/getTradeQuote/getTradeQuote.ts

@@ -25,7 +25,7 @@ export const getTradeQuote = async (
   })
 
   if (maybeContext.isErr()) return Err(maybeContext.unwrapErr())
-  const { tradeCommon, stepCommon, protocolFees, stepDataArgs } = maybeContext.unwrap()
+  const { tradeCommon, stepCommon, protocolFees, stepDataArgs, deadline } = maybeContext.unwrap()
 
   const maybeStepData = await getAcrossStepData({ ...stepDataArgs, type: 'quote', input })
 
@@ -35,6 +35,7 @@ export const getTradeQuote = async (
   const tradeQuote: TradeQuote = {
     ...tradeCommon,
     quoteOrRate: 'quote' as const,
+    deadline,
     receiveAddress,
     steps: [
       {

packages/swapper/src/swappers/AcrossSwapper/utils/getAcrossTradeContext.ts

@@ -22,7 +22,7 @@ import type {
 import { SwapperName, TradeQuoteError } from '../../../types'
 import { getInputOutputRate, makeSwapErrorRight } from '../../../utils'
 import { buildAffiliateFee } from '../../../utils/affiliateFee'
-import { getTreasuryAddressFromChainId } from '../../../utils/helpers'
+import { getTreasuryAddressFromChainId, normalizeEpochToMs } from '../../../utils/helpers'
 import { acrossChainIdToChainId, acrossErrorCodeToTradeQuoteError } from '../constant'
 import { fetchAcrossTrade } from './fetchAcrossTrade'
 import type { GetAcrossStepDataArgs } from './getAcrossStepData'
@@ -35,6 +35,7 @@ type AcrossTradeContext = {
   stepCommon: Omit<TradeStepCommon, 'feeData'>
   protocolFees: QuoteFeeData['protocolFees']
   stepDataArgs: Omit<GetAcrossStepDataArgs, 'type' | 'input'>
+  deadline: number
 }
 
 export const getAcrossTradeContext = async ({
@@ -246,5 +247,6 @@ export const getAcrossTradeContext = async ({
       fallbackNetworkFeeCryptoBaseUnit: quote.fees.originGas.amount,
       deps,
     },
+    deadline: normalizeEpochToMs(quote.quoteExpiryTimestamp),
   })
 }

packages/swapper/src/swappers/ArbitrumBridgeSwapper/getTradeQuote/getTradeQuote.ts

@@ -9,6 +9,7 @@ import type {
   TradeQuote,
 } from '../../../types'
 import { assertQuoteAddresses } from '../../../utils'
+import { FALLBACK_QUOTE_DEADLINE_MS } from '../../../utils/helpers'
 import type { ArbitrumBridgeTradeQuoteInput } from '../types'
 import { getArbitrumBridgeStepData } from '../utils/getArbitrumBridgeStepData'
 import { getArbitrumBridgeTradeContext } from '../utils/getArbitrumBridgeTradeContext'
@@ -53,6 +54,7 @@ export const getTradeQuote = async (
   const tradeQuote: TradeQuote = {
     ...tradeCommon,
     quoteOrRate: 'quote',
+    deadline: Date.now() + FALLBACK_QUOTE_DEADLINE_MS,
     receiveAddress,
     steps: [
       {

packages/swapper/src/swappers/AvnuSwapper/swapperApi/getTradeQuote.ts

@@ -5,6 +5,7 @@ import { validateAndParseAddress } from 'starknet'
 import type { SwapErrorRight, SwapperDeps, TradeQuote } from '../../../types'
 import { TradeQuoteError } from '../../../types'
 import { assertQuoteAddresses, makeSwapErrorRight } from '../../../utils'
+import { FALLBACK_QUOTE_DEADLINE_MS } from '../../../utils/helpers'
 import type { AvnuTradeQuoteInput } from '../types'
 import { getAvnuTradeContext } from '../utils/getAvnuTradeContext'
 
@@ -27,7 +28,7 @@ export const getTradeQuote = async (
     const maybeContext = await getAvnuTradeContext({ input, takerAddress: normalizedSendAddress })
 
     if (maybeContext.isErr()) return Err(maybeContext.unwrapErr())
-    const { tradeCommon, stepCommon, protocolFees, quoteId, sellTokenAddress } =
+    const { tradeCommon, stepCommon, protocolFees, quoteId, sellTokenAddress, deadline } =
       maybeContext.unwrap()
 
     const adapter = deps.assertGetStarknetChainAdapter(sellAsset.chainId)
@@ -46,6 +47,7 @@ export const getTradeQuote = async (
       ...tradeCommon,
       receiveAddress: normalizedReceiveAddress,
       quoteOrRate: 'quote',
+      deadline: deadline ?? Date.now() + FALLBACK_QUOTE_DEADLINE_MS,
       steps: [
         {
           ...stepCommon,

packages/swapper/src/swappers/AvnuSwapper/utils/getAvnuTradeContext.ts

@@ -17,7 +17,7 @@ import type {
 import { SwapperName, TradeQuoteError } from '../../../types'
 import { getInputOutputRate, makeSwapErrorRight } from '../../../utils'
 import { buildAffiliateFee } from '../../../utils/affiliateFee'
-import { getTreasuryAddressFromChainId } from '../../../utils/helpers'
+import { getTreasuryAddressFromChainId, normalizeEpochToMs } from '../../../utils/helpers'
 import { assertValidTrade, getTokenAddress } from './helpers'
 
 type AvnuTradeContext = {
@@ -26,6 +26,7 @@ type AvnuTradeContext = {
   protocolFees: QuoteFeeData['protocolFees']
   quoteId: string
   sellTokenAddress: string
+  deadline: number | undefined
 }
 
 export const getAvnuTradeContext = async ({
@@ -135,6 +136,7 @@ export const getAvnuTradeContext = async ({
       protocolFees,
       quoteId: bestQuote.quoteId,
       sellTokenAddress,
+      deadline: bestQuote.expiry ? normalizeEpochToMs(bestQuote.expiry) : undefined,
     })
   } catch (error) {
     return Err(

packages/swapper/src/swappers/BebopSwapper/getBebopSolanaTradeQuote/getBebopSolanaTradeQuote.ts

@@ -9,6 +9,7 @@ import type {
 } from '../../../types'
 import { TradeQuoteError } from '../../../types'
 import { assertQuoteAddresses, makeSwapErrorRight } from '../../../utils'
+import { normalizeEpochToMs } from '../../../utils/helpers'
 import { getBebopSolanaTradeContext } from '../utils/getBebopSolanaTradeContext'
 import { isBebopSolanaTxSafe } from '../utils/helpers'
 
@@ -44,6 +45,8 @@ export const getBebopSolanaTradeQuote = async (
   const tradeQuote: TradeQuote = {
     ...tradeCommon,
     quoteOrRate: 'quote',
+    // The sealed multi-signer tx is blockhash-pinned, so the provider expiry governs
+    deadline: normalizeEpochToMs(response.expiry),
     receiveAddress,
     steps: [
       {

packages/swapper/src/swappers/BebopSwapper/getBebopTradeQuote/getBebopTradeQuote.ts

@@ -25,7 +25,7 @@ export const getBebopTradeQuote = async (
   })
 
   if (maybeContext.isErr()) return Err(maybeContext.unwrapErr())
-  const { tradeCommon, stepCommon, stepDataArgs } = maybeContext.unwrap()
+  const { tradeCommon, stepCommon, stepDataArgs, deadline } = maybeContext.unwrap()
 
   const maybeStepData = await getBebopStepData({ ...stepDataArgs, type: 'quote', input })
 
@@ -35,6 +35,7 @@ export const getBebopTradeQuote = async (
   const tradeQuote: TradeQuote = {
     ...tradeCommon,
     quoteOrRate: 'quote',
+    deadline,
     receiveAddress,
     steps: [
       {

packages/swapper/src/swappers/BebopSwapper/utils/getBebopTradeContext.ts

@@ -16,7 +16,7 @@ import type {
 import { SwapperName, TradeQuoteError } from '../../../types'
 import { makeSwapErrorRight } from '../../../utils'
 import { buildAffiliateFee } from '../../../utils/affiliateFee'
-import { isNativeEvmAsset } from '../../../utils/helpers'
+import { isNativeEvmAsset, normalizeEpochToMs } from '../../../utils/helpers'
 import { fetchBebopQuote } from './fetchFromBebop'
 import type { GetBebopStepDataArgs } from './getBebopStepData'
 import { assertValidTrade, calculateRate } from './helpers'
@@ -25,6 +25,7 @@ type BebopTradeContext = {
   tradeCommon: TradeCommon
   stepCommon: Omit<TradeStepCommon, 'feeData'>
   stepDataArgs: Omit<GetBebopStepDataArgs, 'type' | 'input'>
+  deadline: number
 }
 
 export const getBebopTradeContext = async ({
@@ -119,5 +120,6 @@ export const getBebopTradeContext = async ({
       from,
       deps,
     },
+    deadline: normalizeEpochToMs(quote.expiry),
   })
 }

packages/swapper/src/swappers/BobGatewaySwapper/swapperApi/getTradeQuote.ts

@@ -4,6 +4,7 @@ import { Err, Ok } from '@sniptt/monads'
 
 import type { SwapErrorRight, SwapperDeps, TradeQuote } from '../../../types'
 import { assertQuoteAddresses } from '../../../utils'
+import { FALLBACK_QUOTE_DEADLINE_MS } from '../../../utils/helpers'
 import type { BobGatewayTradeQuoteInput } from '../types'
 import { getBobGatewayStepData } from '../utils/getBobGatewayStepData'
 import { getBobGatewayTradeContext } from '../utils/getBobGatewayTradeContext'
@@ -46,6 +47,7 @@ export const getBobGatewayTradeQuote = async (
   const tradeQuote: TradeQuote = {
     ...tradeCommon,
     quoteOrRate: 'quote',
+    deadline: Date.now() + FALLBACK_QUOTE_DEADLINE_MS,
     receiveAddress,
     steps: [
       {

packages/swapper/src/swappers/ButterSwap/swapperApi/getTradeQuote.ts

@@ -7,6 +7,7 @@ import { getDefaultSlippageDecimalPercentageForSwapper } from '../../../constant
 import type { SwapErrorRight, SwapperDeps, TradeQuote } from '../../../types'
 import { SwapperName, TradeQuoteError } from '../../../types'
 import { assertQuoteAddresses, makeSwapErrorRight } from '../../../utils'
+import { FALLBACK_QUOTE_DEADLINE_MS } from '../../../utils/helpers'
 import type { ButterSwapTradeQuoteInput } from '../types'
 import { getButterSwapStepData } from '../utils/getButterSwapStepData'
 import { getButterSwapTradeContext } from '../utils/getButterSwapTradeContext'
@@ -82,6 +83,7 @@ export const getTradeQuote = async (
   const tradeQuote: TradeQuote = {
     ...tradeCommon,
     quoteOrRate: 'quote' as const,
+    deadline: Date.now() + FALLBACK_QUOTE_DEADLINE_MS,
     receiveAddress,
     steps: [
       {

packages/swapper/src/swappers/CetusSwapper/swapperApi/getTradeQuote.ts

@@ -3,6 +3,7 @@ import { Err, Ok } from '@sniptt/monads'
 
 import type { SwapErrorRight, SwapperDeps, TradeQuote } from '../../../types'
 import { assertQuoteAddresses } from '../../../utils'
+import { FALLBACK_QUOTE_DEADLINE_MS } from '../../../utils/helpers'
 import type { CetusTradeQuoteInput } from '../types'
 import { getCetusStepData } from './getCetusStepData'
 import { getCetusTradeContext } from './getCetusTradeContext'
@@ -36,6 +37,7 @@ export const getTradeQuote = async (
   const tradeQuote: TradeQuote = {
     ...tradeCommon,
     quoteOrRate: 'quote' as const,
+    deadline: Date.now() + FALLBACK_QUOTE_DEADLINE_MS,
     receiveAddress,
     steps: [
       {