tapimo 0.15.1 → 0.18.0

package/src/internal/routes/providers/relay.test.ts

@@ -3,9 +3,16 @@ import { Address, Hash, Hex } from 'ox'
 import * as TestApp from '../../../../test/App.js'
 import * as TestRelay from '../../../../test/Relay.js'
 import * as TestRoutes from '../../../../test/Routes.js'
+import * as RoutesCatalog from '../../../db/tables/routesCatalog.js'
+import * as Organizations from '../../../db/tables/organizations.js'
 import * as RoutesDepositRequestObservations from '../../../db/tables/routesDepositRequestObservations.js'
+import * as RoutesPolicies from '../../../db/tables/routesPolicies.js'
+import type * as Log from '../../Log.js'
+import * as Store from '../../Store.js'
 import * as DepositAddress from '../DepositAddress.js'
+import * as Chain from '../Chain.js'
 import * as RoutesProvider from '../Provider.js'
+import * as Across from './across.js'
 import * as Relay from './relay.js'
 
 const apiKey = process.env.RELAY_API_KEY
@@ -185,6 +192,8 @@ describe.skipIf(!apiKey)('relay.createDepositAddress (live)', () => {
         "amount": "100000000",
         "destinationChainId": 4217,
         "destinationCurrency": "0x20c00000000000000000000014f22ca97301eb73",
+        "fixedRate": "1:1",
+        "maxSubsidizationAmount": "100000000",
         "originChainId": 728126428,
         "originCurrency": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
         "recipient": "0x2222222222222222222222222222222222222222",
@@ -215,6 +224,7 @@ describe.skipIf(!apiKey)('relay.createDepositAddress (live)', () => {
         "address": Any<String>,
         "correlation": {
           "checkEndpoint": Any<String>,
+          "fixedRate": "1:1",
           "requestId": Any<String>,
         },
         "destinationAmount": Any<String>,
@@ -395,6 +405,32 @@ describe('parseDepositAddressRequests', () => {
 })
 
 describe('relay.listDepositAddressRequests', () => {
+  test('enforces the account-specific requests-v3 quota', async () => {
+    const now = new Date('2026-09-24T12:00:00.000Z')
+    const rateLimitStore = Store.memory()
+    await rateLimitStore.put(
+      'routes:relay:requests-v3',
+      JSON.stringify({ bucket: Math.floor(now.getTime() / 1_000), count: 20, tenants: [] }),
+    )
+    let requested = false
+    const provider = Relay.relay({
+      fetch: async () => {
+        requested = true
+        throw new Error('unexpected request')
+      },
+      now: () => now,
+      rateLimitStore,
+    })
+
+    await expect(
+      provider.listDepositAddressRequests!(
+        { address: `0x${'11'.repeat(20)}` },
+        new AbortController().signal,
+      ),
+    ).rejects.toBeInstanceOf(RoutesProvider.ProviderRateLimitError)
+    expect(requested).toBe(false)
+  })
+
   test('preserves completed deposit evidence when fee sponsorship is null', async () => {
     const server = await TestRelay.createServer((_request, response) => {
       response.writeHead(200, { 'content-type': 'application/json' })
@@ -454,49 +490,52 @@ describe('relay.listDepositAddressRequests', () => {
     }
   })
 
-  test('returns the actual provider subsidy amount and token', async () => {
-    const server = await TestRelay.createServer((_request, response) => {
-      response.writeHead(200, { 'content-type': 'application/json' })
-      response.end(
-        JSON.stringify({
-          requests: [
-            {
-              createdAt: '2026-09-02T00:00:00.000Z',
-              data: {
-                feeSponsorship: {
-                  actual: {
-                    sponsorPayment: {
-                      address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
-                      amount: '23838',
-                      chainId: 8453,
+  test.each(['base', 'tron'] as const)(
+    'returns actual sponsor payments for %s deposits',
+    async (source) => {
+      const server = await TestRelay.createServer((_request, response) => {
+        response.writeHead(200, { 'content-type': 'application/json' })
+        response.end(
+          JSON.stringify({
+            requests: [
+              {
+                createdAt: '2026-09-02T00:00:00.000Z',
+                data: {
+                  feeSponsorship: {
+                    actual: {
+                      sponsorPayment: {
+                        address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+                        amount: '23838',
+                        chainId: 8453,
+                      },
                     },
                   },
+                  outTxs: [],
                 },
-                outTxs: [],
+                id: 'relay-sponsored-request',
+                status: 'success',
+                updatedAt: '2026-09-02T00:00:10.000Z',
               },
-              id: 'relay-sponsored-request',
-              status: 'success',
-              updatedAt: '2026-09-02T00:00:10.000Z',
-            },
-          ],
-        }),
-      )
-    })
+            ],
+          }),
+        )
+      })
 
-    try {
-      const provider = Relay.relay({ apiKey: 'relay-api-key', baseUrl: server.url })
-      const candidate = candidateFor(provider)
+      try {
+        const provider = Relay.relay({ apiKey: 'relay-api-key', baseUrl: server.url })
+        const candidate =
+          source === 'base' ? candidateFor(provider) : depositAddressInput(provider).candidate
 
-      await expect(
-        provider.listDepositAddressRequests!(
-          {
-            address: `0x${'11'.repeat(20)}`,
-            destinationToken: candidate.destinationToken,
-            sourceToken: candidate.sourceToken,
-          },
-          new AbortController().signal,
-        ),
-      ).resolves.toMatchInlineSnapshot(`
+        await expect(
+          provider.listDepositAddressRequests!(
+            {
+              address: `0x${'11'.repeat(20)}`,
+              destinationToken: candidate.destinationToken,
+              sourceToken: candidate.sourceToken,
+            },
+            new AbortController().signal,
+          ),
+        ).resolves.toMatchInlineSnapshot(`
         {
           "requests": [
             {
@@ -530,10 +569,11 @@ describe('relay.listDepositAddressRequests', () => {
           ],
         }
       `)
-    } finally {
-      await server.closeAsync()
-    }
-  })
+      } finally {
+        await server.closeAsync()
+      }
+    },
+  )
 
   test('omits unfinished output transaction hashes', async () => {
     const server = await TestRelay.createServer((_request, response) => {
@@ -587,6 +627,140 @@ describe('relay.listDepositAddressRequests', () => {
 })
 
 describe('relay.createDepositAddress', () => {
+  test('reserves the last two quote slots for executable operations', async () => {
+    const now = new Date('2026-09-24T12:00:00.000Z')
+    const rateLimitStore = Store.memory()
+    const key = 'routes:relay:quote-v2'
+    const quota = (count: number) =>
+      JSON.stringify({ bucket: Math.floor(now.getTime() / 1_000), count, tenants: [] })
+    const upstream = new Error('upstream reached')
+    const provider = Relay.relay({
+      fetch: async () => {
+        throw upstream
+      },
+      now: () => now,
+      rateLimitStore,
+    })
+
+    await rateLimitStore.put(key, quota(8))
+    await expect(
+      provider.createDepositAddress!(depositAddressInput(provider), new AbortController().signal),
+    ).rejects.toBe(upstream)
+    expect(JSON.parse((await rateLimitStore.get(key))!).count).toBe(9)
+
+    await rateLimitStore.put(key, quota(10))
+    await expect(
+      provider.createDepositAddress!(depositAddressInput(provider), new AbortController().signal),
+    ).rejects.toBeInstanceOf(RoutesProvider.ProviderRateLimitError)
+    expect(await rateLimitStore.get(key)).toBe(quota(10))
+  })
+
+  test.each([
+    { amount: '100000000', decimals: 6, isFixedRate: false, subsidize: false },
+    { amount: '100000000', decimals: 6, isFixedRate: false, subsidize: true },
+    { amount: '100000000', decimals: 6, isFixedRate: undefined, subsidize: true },
+    { amount: '100000000', decimals: 6, isFixedRate: true, subsidize: true },
+    { amount: '100000000', decimals: 6, fallback: true, isFixedRate: true, subsidize: true },
+    { amount: '100000000000000000000', decimals: 18, isFixedRate: true, subsidize: true },
+  ])('accepts 1:1 output with slippage minima: %j', async (scenario) => {
+    let body: Record<string, unknown> | undefined
+    const server = await TestRelay.createServer(async (request, response) => {
+      request.setEncoding('utf8')
+      let payload = ''
+      for await (const chunk of request) payload += chunk
+      body = JSON.parse(payload)
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(
+        JSON.stringify({
+          details: {
+            currencyIn: { amount: scenario.amount },
+            currencyOut: { amount: '100000000', minimumAmount: '98000000' },
+            isFixedRate: scenario.isFixedRate,
+          },
+          steps: [
+            {
+              depositAddress: 'TJRabPrwbZy45sbavfcjinPJC18kjpRTv8',
+              requestId: 'relay-fixed-rate',
+            },
+          ],
+        }),
+      )
+    })
+    try {
+      const provider = Relay.relay({ baseUrl: server.url, subsidies: { maxAmount: '100' } })
+      const input = depositAddressInput(provider)
+      const result = await provider.createDepositAddress!(
+        {
+          ...input,
+          amount: scenario.amount,
+          candidate: {
+            ...input.candidate,
+            sourceToken: { ...input.candidate.sourceToken, decimals: scenario.decimals },
+          },
+          subsidize: scenario.subsidize,
+          subsidyMaxAmount: 'fallback' in scenario ? undefined : '0.05',
+        },
+        new AbortController().signal,
+      )
+      expect(body).toMatchObject({
+        amount: scenario.amount,
+        subsidizeFees: scenario.subsidize,
+        tradeType: 'EXACT_INPUT',
+        useDepositAddress: true,
+      })
+      if (scenario.subsidize) {
+        expect(body).toMatchObject({
+          fixedRate: '1:1',
+          maxSubsidizationAmount: 'fallback' in scenario ? '100000000' : '50000',
+        })
+        expect(result.correlation.fixedRate).toBe('1:1')
+      } else {
+        expect(body).not.toHaveProperty('fixedRate')
+        expect(body).not.toHaveProperty('maxSubsidizationAmount')
+        expect(result.correlation).not.toHaveProperty('fixedRate')
+      }
+      expect(result.destinationAmount).toBe('100000000')
+      expect(result.destinationAmountMin).toBe('98000000')
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test.each([
+    { amount: '99000000', isFixedRate: true, minimumAmount: '99000000' },
+    { amount: '100000001', isFixedRate: true, minimumAmount: '98000000' },
+  ])('rejects sponsored quotes without exact 1:1 output: %j', async (scenario) => {
+    const server = await TestRelay.createServer((_request, response) => {
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(
+        JSON.stringify({
+          details: {
+            currencyIn: { amount: '100000000' },
+            currencyOut: { amount: scenario.amount, minimumAmount: scenario.minimumAmount },
+            isFixedRate: scenario.isFixedRate,
+          },
+          steps: [
+            { depositAddress: 'TJRabPrwbZy45sbavfcjinPJC18kjpRTv8', requestId: 'relay-fixed-rate' },
+          ],
+        }),
+      )
+    })
+    try {
+      const provider = Relay.relay({ baseUrl: server.url, subsidies: { maxAmount: '100' } })
+      await expect(
+        provider.createDepositAddress!(
+          {
+            ...depositAddressInput(provider),
+            subsidize: true,
+          },
+          new AbortController().signal,
+        ),
+      ).rejects.toThrow(RoutesProvider.ProviderPayloadError)
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
   test('rejects subsidized provisioning outside the configured limit', async () => {
     const provider = Relay.relay({ subsidies: { maxAmount: '1' } })
 
@@ -600,6 +774,84 @@ describe('relay.createDepositAddress', () => {
 })
 
 describe('relay.prepareTransfer', () => {
+  test('prepares the curated Tempo USDC.e to Solana USDC route', async () => {
+    let requestBody: Record<string, unknown> | undefined
+    const server = await TestRelay.createServer(async (request, response) => {
+      let payload = ''
+      for await (const chunk of request) payload += chunk
+      requestBody = JSON.parse(payload)
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(
+        JSON.stringify({
+          details: {
+            currencyIn: { amount: '5000000' },
+            currencyOut: { amount: '4970000', minimumAmount: '4960000' },
+          },
+          steps: [
+            {
+              id: 'deposit',
+              items: [
+                {
+                  data: {
+                    chainId: 4217,
+                    data: '0x1234',
+                    from: sender,
+                    to: '0x3333333333333333333333333333333333333333',
+                    value: '0',
+                  },
+                },
+              ],
+              kind: 'transaction',
+              requestId: 'relay-tempo-solana',
+            },
+          ],
+        }),
+      )
+    })
+    try {
+      const provider = Relay.relay({ baseUrl: server.url })
+      const candidate = RoutesProvider.getQuoteCandidates({
+        catalog: TestRoutes.snapshot,
+        destinationChain: 'solana',
+        destinationToken: 'USDC',
+        providers: [provider],
+        sourceAmount: '5000000',
+        sourceAmountUnits: 'baseUnits',
+        sourceChain: 'tempo',
+        sourceToken: 'USDC.e',
+      }).find((entry) => entry.id === 'tempo-usdce-solana-usdc-relay')
+      if (!candidate) throw new Error('Expected the Relay Tempo to Solana candidate.')
+      const solanaRecipient = '7ZwiMrYFNCzZ4TcPkeMx7BTZSZ9jDgGR8H8Nkazhr6L1'
+      const result = await provider.prepareTransfer!(
+        {
+          candidate,
+          method: 'transaction',
+          mode: 'exactSource',
+          recipient: solanaRecipient,
+          sender,
+        },
+        new AbortController().signal,
+      )
+      expect(requestBody).toMatchObject({
+        amount: '5000000',
+        destinationChainId: 792703809,
+        destinationCurrency: candidate.destinationToken.address,
+        originChainId: 4217,
+        originCurrency: candidate.sourceToken.address,
+        recipient: solanaRecipient,
+        user: sender,
+      })
+      expect(result).toMatchObject({
+        action: { type: 'evm:calls' },
+        correlation: { requestId: 'relay-tempo-solana' },
+        destinationAmount: '4970000',
+        destinationAmountMin: '4960000',
+      })
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
   test('refuses methods and modes it cannot prepare', async () => {
     const provider = Relay.relay()
     await expect(
@@ -611,6 +863,570 @@ describe('relay.prepareTransfer', () => {
   })
 })
 
+describe('relay.verifySourceTransaction', () => {
+  test('bounds the Relay chain lookup', async () => {
+    const snapshot = TestRoutes.transferSnapshot()
+    const transactionHash = `0x${'aa'.repeat(32)}`
+    const server = await TestRelay.createServer((request, response) => {
+      request.resume()
+      if (!request.url?.startsWith('/requests/v3')) return
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(
+        JSON.stringify({
+          requests: [
+            {
+              data: { inTxs: [{ chainId: 8453, status: 'success', txHash: transactionHash }] },
+              id: 'base-to-tempo',
+              recipient: snapshot.recipient,
+              sender: snapshot.sender,
+              status: 'pending',
+            },
+          ],
+        }),
+      )
+    })
+    try {
+      const provider = Relay.relay({
+        apiKey: 'relay-api-key',
+        baseUrl: server.url,
+        observation: { db },
+      })
+      const options = {
+        destinationChain: TestRoutes.snapshot.chainsByKey.get(snapshot.destinationChain.id)!,
+        providerState: { requestId: 'base-to-tempo' },
+        sourceChain: TestRoutes.snapshot.chainsByKey.get(snapshot.sourceChain.id)!,
+        transactionHash,
+        transfer: snapshot,
+      }
+      await expect(
+        provider.verifySourceTransaction!(options, new AbortController().signal),
+      ).rejects.toBeInstanceOf(RoutesProvider.ProviderTimeoutError)
+    } finally {
+      server.closeAllConnections()
+      await server.closeAsync()
+    }
+  }, 15_000)
+
+  test.each([
+    { sourceStatus: 'pending', type: 'pending' },
+    { sourceStatus: 'submitted', type: 'pending' },
+    { sourceStatus: 'failure', type: 'invalid' },
+  ])(
+    'accepts the Base to Tempo route and treats $sourceStatus as $type',
+    async ({ sourceStatus, type }) => {
+      const transactionHash = `0x${'aa'.repeat(32)}`
+      const snapshot = TestRoutes.transferSnapshot({
+        destinationToken: {
+          ...TestRoutes.transferSnapshot().destinationToken,
+          address: '0x20c0000000000000000000000000000000000000',
+          name: 'pathUSD',
+          symbol: 'pathUSD',
+        },
+      })
+      const server = await TestRelay.createServer((_request, response) => {
+        response.writeHead(200, { 'content-type': 'application/json' })
+        response.end(
+          JSON.stringify({
+            requests: [
+              {
+                data: {
+                  inTxs: [
+                    { chainId: 8453, status: 'pending', txHash: null },
+                    { chainId: 8453, status: sourceStatus, txHash: transactionHash },
+                  ],
+                },
+                id: 'base-to-tempo',
+                recipient: snapshot.recipient,
+                sender: snapshot.sender,
+                status: 'pending',
+              },
+            ],
+          }),
+        )
+      })
+      try {
+        const provider = Relay.relay({
+          apiKey: 'relay-api-key',
+          baseUrl: server.url,
+          observation: { db },
+        })
+        const options = {
+          destinationChain: TestRoutes.snapshot.chainsByKey.get(snapshot.destinationChain.id)!,
+          providerState: { requestId: 'base-to-tempo' },
+          sourceChain: TestRoutes.snapshot.chainsByKey.get(snapshot.sourceChain.id)!,
+          transactionHash,
+          transfer: snapshot,
+        }
+        await expect(
+          provider.verifySourceTransaction!(options, new AbortController().signal),
+        ).resolves.toEqual({ type })
+      } finally {
+        await server.closeAsync()
+      }
+    },
+  )
+
+  test('keeps unfinished Tempo delivery pending', async () => {
+    const snapshot = TestRoutes.transferSnapshot({
+      destinationToken: {
+        ...TestRoutes.transferSnapshot().destinationToken,
+        address: '0x20c0000000000000000000000000000000000000',
+        name: 'pathUSD',
+        symbol: 'pathUSD',
+      },
+    })
+    const server = await TestRelay.createServer((_request, response) => {
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(
+        JSON.stringify({
+          requests: [
+            {
+              id: 'base-to-tempo',
+              recipient: snapshot.recipient,
+              sender: snapshot.sender,
+              status: 'pending',
+            },
+          ],
+        }),
+      )
+    })
+    try {
+      const provider = Relay.relay({
+        apiKey: 'relay-api-key',
+        baseUrl: server.url,
+        observation: { db },
+      })
+      await expect(
+        provider.verifyDestinationDelivery!(
+          {
+            destinationChain: TestRoutes.snapshot.chainsByKey.get(snapshot.destinationChain.id)!,
+            providerState: { requestId: 'base-to-tempo' },
+            sourceChain: TestRoutes.snapshot.chainsByKey.get(snapshot.sourceChain.id)!,
+            transfer: snapshot,
+          },
+          new AbortController().signal,
+        ),
+      ).resolves.toEqual({ type: 'pending' })
+    } finally {
+      await server.closeAsync()
+    }
+  })
+})
+
+describe('relay.verifyDestinationDelivery', () => {
+  test('keeps successful Relay outputs pending until their hash is assigned', async () => {
+    const snapshot = TestRoutes.transferSnapshot()
+    const server = await TestRelay.createServer((_request, response) => {
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(
+        JSON.stringify({
+          requests: [
+            {
+              data: {
+                outTxs: [{ chainId: 4217, status: 'success', txHash: null }],
+                route: {
+                  actual: {
+                    destination: {
+                      outputCurrency: {
+                        amount: '979295',
+                        currency: { address: snapshot.destinationToken.address, chainId: 4217 },
+                      },
+                    },
+                  },
+                },
+              },
+              id: 'base-to-tempo',
+              recipient: snapshot.recipient,
+              sender: snapshot.sender,
+              status: 'success',
+            },
+          ],
+        }),
+      )
+    })
+    try {
+      const provider = Relay.relay({
+        apiKey: 'relay-api-key',
+        baseUrl: server.url,
+        observation: { db },
+      })
+      await expect(
+        provider.verifyDestinationDelivery!(
+          {
+            destinationChain: TestRoutes.snapshot.chainsByKey.get(snapshot.destinationChain.id)!,
+            providerState: { requestId: 'base-to-tempo' },
+            sourceChain: TestRoutes.snapshot.chainsByKey.get(snapshot.sourceChain.id)!,
+            transfer: snapshot,
+          },
+          new AbortController().signal,
+        ),
+      ).resolves.toEqual({ type: 'pending' })
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test.each([
+    { recipient: '0xAaAaAaAaAaAaAaAaAaAaAaAaAaAaAaAaAaAaAaAa', type: 'pending' },
+    { recipient: 'not-an-address', type: 'invalid' },
+  ])('compares EVM recipients by address value: $recipient', async ({ recipient, type }) => {
+    const snapshot = TestRoutes.transferSnapshot({
+      recipient: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+    })
+    const server = await TestRelay.createServer((_request, response) => {
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(
+        JSON.stringify({
+          requests: [
+            { id: 'base-to-tempo', recipient, sender: snapshot.sender, status: 'pending' },
+          ],
+        }),
+      )
+    })
+    try {
+      const provider = Relay.relay({
+        apiKey: 'relay-api-key',
+        baseUrl: server.url,
+        observation: { db },
+      })
+      await expect(
+        provider.verifyDestinationDelivery!(
+          {
+            destinationChain: TestRoutes.snapshot.chainsByKey.get(snapshot.destinationChain.id)!,
+            providerState: { requestId: 'base-to-tempo' },
+            sourceChain: TestRoutes.snapshot.chainsByKey.get(snapshot.sourceChain.id)!,
+            transfer: snapshot,
+          },
+          new AbortController().signal,
+        ),
+      ).resolves.toEqual({ type })
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test.each([
+    { address: '0x20C000000000000000000000B9537D11C60E8B50', type: 'pending' },
+    { address: 'not-an-address', type: 'invalid' },
+  ])('compares EVM destination tokens by address value: $address', async ({ address, type }) => {
+    const snapshot = TestRoutes.transferSnapshot()
+    const server = await TestRelay.createServer((_request, response) => {
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(
+        JSON.stringify({
+          requests: [
+            {
+              data: {
+                route: {
+                  actual: {
+                    destination: {
+                      outputCurrency: { amount: '979295', currency: { address, chainId: 4217 } },
+                    },
+                  },
+                },
+              },
+              id: 'base-to-tempo',
+              recipient: snapshot.recipient,
+              sender: snapshot.sender,
+              status: 'pending',
+            },
+          ],
+        }),
+      )
+    })
+    try {
+      const provider = Relay.relay({
+        apiKey: 'relay-api-key',
+        baseUrl: server.url,
+        observation: { db },
+      })
+      await expect(
+        provider.verifyDestinationDelivery!(
+          {
+            destinationChain: TestRoutes.snapshot.chainsByKey.get(snapshot.destinationChain.id)!,
+            providerState: { requestId: 'base-to-tempo' },
+            sourceChain: TestRoutes.snapshot.chainsByKey.get(snapshot.sourceChain.id)!,
+            transfer: snapshot,
+          },
+          new AbortController().signal,
+        ),
+      ).resolves.toEqual({ type })
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test('requires exact Solana recipient and token addresses', async () => {
+    const snapshot = TestRoutes.transferSnapshot({
+      destinationChain: {
+        addressFormat: 'base58',
+        id: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+        kind: 'solana',
+        name: 'Solana',
+      },
+      destinationToken: {
+        ...TestRoutes.transferSnapshot().destinationToken,
+        address: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+      },
+      recipient: '7ZwiMrYFNCzZ4TcPkeMx7BTZSZ9jDgGR8H8Nkazhr6L1',
+    })
+    const server = await TestRelay.createServer((_request, response) => {
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(
+        JSON.stringify({
+          requests: [
+            {
+              data: {
+                route: {
+                  actual: {
+                    destination: {
+                      outputCurrency: {
+                        amount: '979295',
+                        currency: {
+                          address: snapshot.destinationToken.address.toLowerCase(),
+                          chainId: 792703809,
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+              id: 'base-to-solana',
+              recipient: snapshot.recipient,
+              sender: snapshot.sender,
+              status: 'pending',
+            },
+          ],
+        }),
+      )
+    })
+    try {
+      const provider = Relay.relay({
+        apiKey: 'relay-api-key',
+        baseUrl: server.url,
+        observation: { db },
+      })
+      await expect(
+        provider.verifyDestinationDelivery!(
+          {
+            destinationChain: TestRoutes.snapshot.chainsByKey.get(snapshot.destinationChain.id) ??
+              Chain.from({ id: snapshot.destinationChain.id as Chain.Id, name: 'Solana', rpcUrls: [server.url], slug: 'solana' }), // prettier-ignore
+            providerState: { requestId: 'base-to-solana' },
+            sourceChain: TestRoutes.snapshot.chainsByKey.get(snapshot.sourceChain.id)!,
+            transfer: snapshot,
+          },
+          new AbortController().signal,
+        ),
+      ).resolves.toEqual({ type: 'invalid' })
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test('moves Relay fallback to manual recovery', async () => {
+    const snapshot = TestRoutes.transferSnapshot()
+    const server = await TestRelay.createServer((_request, response) => {
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(JSON.stringify({ requests: [{ id: 'base-to-tempo', recipient: snapshot.recipient, sender: snapshot.sender, status: 'fallback' }] })) // prettier-ignore
+    })
+    try {
+      const provider = Relay.relay({
+        apiKey: 'relay-api-key',
+        baseUrl: server.url,
+        observation: { db },
+      })
+      await expect(
+        provider.verifyDestinationDelivery!(
+          {
+            destinationChain: TestRoutes.snapshot.chainsByKey.get(snapshot.destinationChain.id)!,
+            providerState: { requestId: 'base-to-tempo' },
+            sourceChain: TestRoutes.snapshot.chainsByKey.get(snapshot.sourceChain.id)!,
+            transfer: snapshot,
+          },
+          new AbortController().signal,
+        ),
+      ).resolves.toEqual({
+        statusReason: {
+          code: 'manual_recovery_required',
+          message: 'Relay could not complete the destination transfer.',
+        },
+        type: 'action-required',
+      })
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test('bounds Relay request polling and preserves caller cancellation', async () => {
+    const snapshot = TestRoutes.transferSnapshot()
+    const server = await TestRelay.createServer((request) => request.resume())
+    try {
+      const provider = Relay.relay({
+        apiKey: 'relay-api-key',
+        baseUrl: server.url,
+        observation: { db },
+      })
+      const options = {
+        destinationChain: TestRoutes.snapshot.chainsByKey.get(snapshot.destinationChain.id)!,
+        providerState: { requestId: 'base-to-tempo' },
+        sourceChain: TestRoutes.snapshot.chainsByKey.get(snapshot.sourceChain.id)!,
+        transfer: snapshot,
+      }
+      await expect(
+        provider.verifyDestinationDelivery!(options, new AbortController().signal),
+      ).rejects.toBeInstanceOf(RoutesProvider.ProviderTimeoutError)
+      const controller = new AbortController()
+      const request = provider.verifyDestinationDelivery!(options, controller.signal)
+      controller.abort()
+      await expect(request).rejects.toMatchObject({ name: 'AbortError' })
+    } finally {
+      server.closeAllConnections()
+      await server.closeAsync()
+    }
+  }, 15_000)
+
+  test.each([
+    {
+      amount: '939241',
+      expected: {
+        statusReason: {
+          code: 'manual_recovery_required',
+          message: 'Relay delivered less than the quoted minimum destination amount.',
+        },
+        type: 'action-required',
+      },
+    },
+    {
+      amount: '939242',
+      expected: { destinationAmount: '939242', transactionHash: '5wHu1qwD7iCD6aZLQ3xLyRsfNySXgJ7rPcT2fbeK4cjQ', type: 'verified' }, // prettier-ignore
+    },
+  ])('enforces the quoted minimum when Relay reports $amount', async ({ amount, expected }) => {
+    const recipient = '7ZwiMrYFNCzZ4TcPkeMx7BTZSZ9jDgGR8H8Nkazhr6L1'
+    const token = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
+    const transactionHash = '5wHu1qwD7iCD6aZLQ3xLyRsfNySXgJ7rPcT2fbeK4cjQ'
+    const snapshot = TestRoutes.transferSnapshot({
+      destinationChain: {
+        addressFormat: 'base58',
+        id: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+        kind: 'solana',
+        name: 'Solana',
+      },
+      destinationToken: {
+        address: token,
+        currency: 'USD',
+        decimals: 6,
+        name: 'USD Coin',
+        standard: 'SPL',
+        symbol: 'USDC',
+        tokenKey: `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:${token}`,
+        verified: true,
+      },
+      recipient,
+    })
+    const server = await TestRelay.createServer((request, response) => {
+      request.resume()
+      response.writeHead(200, { 'content-type': 'application/json' })
+      if (request.url?.startsWith('/requests/v3')) {
+        response.end(
+          JSON.stringify({
+            requests: [
+              {
+                data: {
+                  outTxs: [{ chainId: 792703809, status: 'success', txHash: transactionHash }],
+                  route: {
+                    actual: {
+                      destination: {
+                        outputCurrency: {
+                          amount,
+                          currency: { address: token, chainId: 792703809 },
+                        },
+                      },
+                    },
+                  },
+                },
+                id: 'base-to-solana',
+                recipient,
+                sender: snapshot.sender,
+                status: 'success',
+              },
+            ],
+          }),
+        )
+        return
+      }
+      response.end(
+        JSON.stringify({
+          id: 1,
+          jsonrpc: '2.0',
+          result: {
+            meta: {
+              err: null,
+              postTokenBalances: [{ accountIndex: 1, mint: token, owner: recipient }],
+            },
+            transaction: {
+              message: {
+                accountKeys: ['Sender1111111111111111111111111111111111', 'RecipientTokenAccount'],
+                instructions: [
+                  {
+                    parsed: {
+                      info: {
+                        destination: 'RecipientTokenAccount',
+                        mint: token,
+                        tokenAmount: { amount },
+                      },
+                      type: 'transferChecked',
+                    },
+                    program: 'spl-token',
+                  },
+                ],
+              },
+            },
+          },
+        }),
+      )
+    })
+    try {
+      await RoutesCatalog.publish(db, {
+        chainTokens: [],
+        chains: [
+          {
+            aliases: [],
+            id: snapshot.destinationChain.id as Chain.Id,
+            name: 'Solana',
+            parentChainId: null,
+            rpcUrls: [server.url],
+            slug: 'solana',
+          },
+        ],
+        routes: [],
+        tokens: [],
+      })
+      const provider = Relay.relay({
+        apiKey: 'relay-api-key',
+        baseUrl: server.url,
+        observation: { db },
+      })
+      const result = await provider.verifyDestinationDelivery!(
+        {
+          destinationChain: Chain.from({
+            id: snapshot.destinationChain.id as Chain.Id,
+            name: 'Solana',
+            rpcUrls: [server.url],
+            slug: 'solana',
+          }),
+          providerState: { requestId: 'base-to-solana' },
+          sourceChain: TestRoutes.snapshot.chainsByKey.get(snapshot.sourceChain.id)!,
+          transfer: snapshot,
+        },
+        new AbortController().signal,
+      )
+      expect(result).toEqual(expected)
+    } finally {
+      await server.closeAsync()
+    }
+  })
+})
+
 describe('verifyWebhook', () => {
   beforeEach(() => vi.useFakeTimers({ now: webhookNow }))
   afterEach(() => vi.useRealTimers())
@@ -747,3 +1563,409 @@ describe('receiveWebhook', () => {
     `)
   })
 })
+
+describe('quote errors', () => {
+  const sourceToken = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
+  const destinationToken = '0x20c000000000000000000000b9537d11c60e8b50'
+  const pathUsd = '0x20c0000000000000000000000000000000000000'
+  const rejection = {
+    errorCode: 'AMOUNT_TOO_LOW',
+    message: 'Swap output amount is too small to cover fees required to execute swap',
+    requestId: '0x1789498645e745767fefcb596a776acd85361596dde3b91908a4a4268235da01',
+  }
+  const request = {
+    destinationToken,
+    sourceAmount: '200000',
+    sourceAmountUnits: 'baseUnits',
+    sourceChain: 'base',
+    sourceToken,
+  } as const
+  const key = {
+    id: 'key_relay_quote_errors',
+    orgId: 'org_relay_quote_errors',
+    scopes: ['data:read', 'routes:read', 'routes:write'],
+    token: 'secret_relay_quote_errors',
+  } satisfies TestApp.kvStore.Key
+
+  beforeAll(async () => {
+    await TestRoutes.publish(db)
+    await Organizations.upsert(db, { id: key.orgId, name: 'Relay quote errors' })
+    await RoutesPolicies.save(db, {
+      policy: { access: null },
+      scope: { environment: 'production', orgId: key.orgId },
+      version: 0,
+    })
+  })
+
+  describe.each(['getQuote', 'prepareTransfer', 'createDepositAddress'] as const)(
+    '%s',
+    (operation) => {
+      test('classifies AMOUNT_TOO_LOW and retains the provider reason', async () => {
+        const server = await quoteServer(400, rejection)
+        try {
+          const provider = Relay.relay({
+            baseUrl: server.url,
+            userAddresses: TestRoutes.relayQuoteUsers,
+          })
+          if (operation === 'getQuote')
+            await expect(invoke(provider, operation)).resolves.toMatchObject({
+              quality: { sourceDetail: 'relay:quote-v2:AMOUNT_TOO_LOW', tier: 'unavailable' },
+              status: 'unavailable',
+            })
+          else
+            await expect(invoke(provider, operation)).rejects.toMatchObject({
+              cause: { body: rejection, status: 400 },
+              message: 'AMOUNT_TOO_LOW',
+              name:
+                operation === 'createDepositAddress'
+                  ? 'RoutesProvider.AmountTooLowError'
+                  : 'RoutesProvider.ProviderUnavailableError',
+            })
+          expect(server.requests).toEqual([
+            expect.objectContaining({
+              amount: '200000',
+              destinationChainId: 4217,
+              destinationCurrency: operation === 'prepareTransfer' ? pathUsd : destinationToken,
+              originChainId: 8453,
+              originCurrency: sourceToken,
+              tradeType: 'EXACT_INPUT',
+              ...(operation === 'createDepositAddress'
+                ? { subsidizeFees: false, useDepositAddress: true }
+                : {}),
+            }),
+          ])
+        } finally {
+          await server.closeAsync()
+        }
+      })
+
+      test.each([
+        { body: { errorCode: 'UNKNOWN_ERROR' }, status: 400 },
+        { body: rejection, status: 500 },
+        { body: { message: rejection.message }, status: 400 },
+      ])('preserves unexpected upstream response $status: $body', async ({ body, status }) => {
+        const server = await quoteServer(status, body)
+        try {
+          const provider = Relay.relay({
+            baseUrl: server.url,
+            userAddresses: TestRoutes.relayQuoteUsers,
+          })
+          await expect(invoke(provider, operation)).rejects.toMatchObject({
+            body,
+            name: 'RoutesProvider.ProviderResponseError',
+            status,
+          })
+        } finally {
+          await server.closeAsync()
+        }
+      })
+
+      test.each(['AMOUNT_TOO_LOW', 'NO_ROUTE'])(
+        'uses the composed API contract for %s',
+        async (errorCode) => {
+          const server = await quoteServer(400, { ...rejection, errorCode })
+          const entries: Log.Entry[] = []
+          try {
+            const app = create(server.url, entries)
+            const response = await apiRequest(app, operation)
+            const body = await response.json()
+            const code = (() => {
+              if (operation === 'getQuote') return 'route_unavailable'
+              if (operation === 'createDepositAddress' && errorCode === 'AMOUNT_TOO_LOW')
+                return 'amount_too_low'
+              return 'quote_not_available'
+            })()
+            expect({ error: { code: body.error.code }, status: response.status }).toEqual({
+              error: { code },
+              status: operation === 'getQuote' || code === 'amount_too_low' ? 400 : 404,
+            })
+            if (code === 'amount_too_low')
+              expect(body.error.message).toMatchInlineSnapshot(
+                `"This amount cannot cover the route fees. Increase the amount or enable subsidies if available."`,
+              )
+            expect(entries.at(-1)?.routesProviderAttempts).toEqual([
+              {
+                durationMs: expect.any(Number),
+                id: 'relay',
+                operation,
+                outcome: 'unavailable',
+              },
+            ])
+            expect(entries.at(-1)?.provider).toBeUndefined()
+            expect(server.requests).toHaveLength(1)
+          } finally {
+            await server.closeAsync()
+          }
+        },
+      )
+
+      test.each([400, 503])('keeps unexpected HTTP %s failures as API 502', async (status) => {
+        const server = await quoteServer(status, { errorCode: 'UNKNOWN_ERROR' })
+        const entries: Log.Entry[] = []
+        try {
+          const response = await apiRequest(create(server.url, entries), operation)
+          expect(response.status).toBe(502)
+          expect((await response.json()).error.code).toBe('upstream_error')
+          expect(entries.at(-1)?.provider).toEqual({
+            code: 'UNKNOWN_ERROR',
+            failure: 'http',
+            id: 'relay',
+            operation,
+            status,
+          })
+        } finally {
+          await server.closeAsync()
+        }
+      })
+    },
+  )
+
+  describe('getQuotes', () => {
+    test('honors Relay Retry-After cooldowns after an upstream 429', async () => {
+      const relay = await quoteServer(429, { errorCode: 'RATE_LIMITED' }, { 'retry-after': '2' })
+      const rateLimitStore = Store.memory()
+      let time = new Date('2026-09-24T12:00:00.000Z')
+      const provider = Relay.relay({
+        baseUrl: relay.url,
+        now: () => time,
+        rateLimitStore,
+        userAddresses: TestRoutes.relayQuoteUsers,
+      })
+
+      try {
+        await expect(invoke(provider, 'getQuote')).rejects.toMatchObject({
+          retryAfterMs: 2_000,
+          status: 429,
+        })
+        time = new Date(time.getTime() + 1_001)
+        await expect(invoke(provider, 'getQuote')).rejects.toBeInstanceOf(
+          RoutesProvider.ProviderRateLimitError,
+        )
+        expect(relay.requests).toHaveLength(1)
+
+        time = new Date(time.getTime() + 1_000)
+        await expect(invoke(provider, 'getQuote')).rejects.toMatchObject({ status: 429 })
+        expect(relay.requests).toHaveLength(2)
+      } finally {
+        await relay.closeAsync()
+      }
+    })
+
+    test('skips Relay when its read quota is exhausted and returns an alternative quote', async () => {
+      const now = new Date('2026-09-24T12:00:00.000Z')
+      const rateLimitStore = Store.memory()
+      await rateLimitStore.put(
+        'routes:relay:quote-v2',
+        JSON.stringify({
+          bucket: Math.floor(now.getTime() / 1_000),
+          count: 8,
+          tenants: [],
+        }),
+      )
+      const relay = await quoteServer(500, { errorCode: 'SHOULD_NOT_BE_CALLED' })
+      const across = await TestRelay.createServer((_request, response) => {
+        response.writeHead(200, { 'content-type': 'application/json' })
+        response.end(
+          JSON.stringify({
+            amountType: 'exactInput',
+            expectedFillTime: 5,
+            expectedOutputAmount: '180000',
+            inputAmount: '200000',
+            inputToken: { address: sourceToken, chainId: 8453, decimals: 6 },
+            minOutputAmount: '175000',
+            outputToken: { address: destinationToken, chainId: 4217, decimals: 6 },
+            quoteExpiryTimestamp: Math.floor(Date.now() / 1_000) + 60,
+          }),
+        )
+      })
+      const entries: Log.Entry[] = []
+      try {
+        const response = await apiRequest(
+          create(
+            relay.url,
+            entries,
+            [
+              Across.across({
+                apiKey: 'local-across',
+                baseUrl: across.url,
+                integratorId: '0xdead',
+                userAddress: sender,
+              }),
+            ],
+            { now: () => now, rateLimitStore },
+          ),
+          'getQuote',
+        )
+        expect(response.status).toBe(200)
+        expect((await response.json()).data).toMatchObject([{ provider: { id: 'across' } }])
+        expect(relay.requests).toHaveLength(0)
+        expect(entries.at(-1)?.routesProviderAttempts).toContainEqual({
+          durationMs: expect.any(Number),
+          failure: 'rate_limit',
+          id: 'relay',
+          operation: 'getQuote',
+          outcome: 'failed',
+          rateLimitSource: 'local',
+        })
+      } finally {
+        await Promise.all([relay.closeAsync(), across.closeAsync()])
+      }
+    })
+
+    test.each([rejection, { errorCode: 'UNKNOWN_ERROR' }])(
+      'returns a valid alternative quote when Relay rejects with $errorCode',
+      async (body) => {
+        const relay = await quoteServer(400, body)
+        const across = await TestRelay.createServer((_request, response) => {
+          response.writeHead(200, { 'content-type': 'application/json' })
+          response.end(
+            JSON.stringify({
+              amountType: 'exactInput',
+              expectedFillTime: 5,
+              expectedOutputAmount: '180000',
+              inputAmount: '200000',
+              inputToken: { address: sourceToken, chainId: 8453, decimals: 6 },
+              minOutputAmount: '175000',
+              outputToken: { address: destinationToken, chainId: 4217, decimals: 6 },
+              quoteExpiryTimestamp: Math.floor(Date.now() / 1000) + 60,
+            }),
+          )
+        })
+        try {
+          const app = create(
+            relay.url,
+            [],
+            [
+              Across.across({
+                apiKey: 'local-across',
+                baseUrl: across.url,
+                integratorId: '0xdead',
+                userAddress: sender,
+              }),
+            ],
+          )
+          const response = await apiRequest(app, 'getQuote')
+          expect(response.status).toBe(200)
+          expect((await response.json()).data).toMatchObject([
+            {
+              destinationAmount: { baseUnits: '180000' },
+              destinationAmountMin: { baseUnits: '175000' },
+              provider: { id: 'across' },
+            },
+          ])
+        } finally {
+          await Promise.all([relay.closeAsync(), across.closeAsync()])
+        }
+      },
+    )
+  })
+
+  function create(
+    url: string,
+    entries: Log.Entry[],
+    alternatives: readonly RoutesProvider.Provider[] = [],
+    relayOptions: Pick<Relay.relay.Options, 'now' | 'rateLimitStore'> = {},
+  ) {
+    return TestApp.create({
+      auth: { keys: [key] },
+      db,
+      defaultChainId: 4217,
+      logger: (entry) => void entries.push(entry),
+      providers: [
+        Relay.relay({
+          baseUrl: url,
+          userAddresses: TestRoutes.relayQuoteUsers,
+          ...relayOptions,
+        }),
+        ...alternatives,
+      ],
+    })
+  }
+
+  function apiRequest(
+    app: ReturnType<typeof create>,
+    operation: 'getQuote' | 'prepareTransfer' | 'createDepositAddress',
+  ) {
+    const headers = { 'tempo-api-key': key.token }
+    if (operation === 'getQuote')
+      return app.request(`/v1/routes/quotes?${new URLSearchParams(request)}`, { headers })
+    return app.request(
+      `/v1/routes/${operation === 'prepareTransfer' ? 'transfers' : 'deposit-addresses'}`,
+      {
+        body: JSON.stringify({
+          amount: '200000',
+          // Relay's published transfer route targets pathUSD, not USDC.e.
+          destinationToken: operation === 'prepareTransfer' ? pathUsd : destinationToken,
+          recipient,
+          sourceChain: 'base',
+          sourceToken,
+          subsidize: false,
+          ...(operation === 'prepareTransfer'
+            ? { mode: 'exactSource', sender }
+            : { refundAddress: sender }),
+        }),
+        headers: {
+          ...headers,
+          'content-type': 'application/json',
+          'idempotency-key': crypto.randomUUID(),
+        },
+        method: 'POST',
+      },
+    )
+  }
+
+  function invoke(
+    provider: RoutesProvider.Provider,
+    operation: 'getQuote' | 'prepareTransfer' | 'createDepositAddress',
+  ) {
+    const candidate = RoutesProvider.getQuoteCandidates({
+      catalog: TestRoutes.snapshot,
+      providers: [provider],
+      ...request,
+      destinationToken: operation === 'prepareTransfer' ? pathUsd : destinationToken,
+    })[0]!
+    const signal = new AbortController().signal
+    if (operation === 'getQuote')
+      return provider.getQuote(
+        {
+          ...candidate,
+          cache: { bypass: true },
+          candidate,
+          quotaKey: 'local',
+          request,
+        },
+        signal,
+      )
+    if (operation === 'prepareTransfer')
+      return provider.prepareTransfer!(
+        { candidate, method: 'transaction', mode: 'exactSource', recipient, sender },
+        signal,
+      )
+    return provider.createDepositAddress!(
+      {
+        amount: '200000',
+        candidate,
+        recipient,
+        refundAddress: sender,
+        subsidize: false,
+      },
+      signal,
+    )
+  }
+})
+
+async function quoteServer(status: number, body: unknown, headers: Record<string, string> = {}) {
+  const requests: unknown[] = []
+  const server = await TestRelay.createServer(async (request, response) => {
+    if (request.method !== 'POST' || request.url !== '/quote/v2') {
+      response.writeHead(404).end()
+      return
+    }
+    const chunks: Buffer[] = []
+    for await (const chunk of request) chunks.push(Buffer.from(chunk))
+    requests.push(JSON.parse(Buffer.concat(chunks).toString()))
+    response.writeHead(status, { 'content-type': 'application/json', ...headers })
+    response.end(JSON.stringify(body))
+  })
+  return Object.assign(server, { requests })
+}