tapimo 0.13.0 → 0.15.0

package/src/internal/{funding → routes}/Provider.test.ts

@@ -1,6 +1,6 @@
-import * as TestFunding from '../../../test/Funding.js'
-import * as FundingCatalog from './Catalog.js'
-import * as FundingProvider from './Provider.js'
+import * as TestRoutes from '../../../test/Routes.js'
+import * as RoutesCatalog from './Catalog.js'
+import * as RoutesProvider from './Provider.js'
 import * as Across from './providers/across.js'
 import * as Relay from './providers/relay.js'
 import * as Rhino from './providers/rhino.js'
@@ -14,7 +14,7 @@ const providers = [
     integratorId: '0xdead',
     userAddress: '0x1111111111111111111111111111111111111111',
   }),
-  Relay.relay({ userAddresses: TestFunding.relayQuoteUsers }),
+  Relay.relay({ userAddresses: TestRoutes.relayQuoteUsers }),
   Rhino.rhino(),
   Squid.squid({
     integratorId: 'squid-integrator-id',
@@ -25,7 +25,8 @@ const providers = [
 ] as const
 
 const baseUsdcRequest = {
-  catalog: TestFunding.snapshot,
+  catalog: TestRoutes.snapshot,
+  destinationChain: 'tempo',
   provider: 'relay',
   sourceAmount: '1000000',
   sourceAmountUnits: 'baseUnits',
@@ -35,7 +36,7 @@ const baseUsdcRequest = {
 
 const depositAddressOptions = {
   amount: '100000000',
-  catalog: TestFunding.snapshot,
+  catalog: TestRoutes.snapshot,
   destinationChainId: 4217,
   destinationToken: '0x20c00000000000000000000014f22ca97301eb73',
   recipient: `0x${'11'.repeat(20)}`,
@@ -46,8 +47,8 @@ const depositAddressOptions = {
 } as const
 
 const prepareOptions = {
-  catalog: TestFunding.snapshot,
-  destinationChainId: 4217,
+  catalog: TestRoutes.snapshot,
+  destinationChain: 'tempo',
   destinationToken: '0x20c0000000000000000000000000000000000000',
   method: 'transaction',
   mode: 'exactSource',
@@ -59,41 +60,257 @@ const prepareOptions = {
 } as const
 
 describe('from', () => {
-  test('registers the funding provider type', () => {
-    expect(providers[0]?.type).toBe('funding')
+  test('registers the route provider type', () => {
+    expect(providers[0]?.type).toBe('routes')
   })
 
   test('rejects provider ids that are not normalized', () => {
     expect(() =>
-      FundingProvider.from({
+      RoutesProvider.from({
         getQuote: async () => ({ sampledAt: '2026-01-01T00:00:00Z', status: 'unavailable' }),
         id: ' Relay ',
         name: 'Relay',
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[FundingProvider.ProviderConfigurationError: Provider ids must be lowercase and trimmed.]`,
+      `[RoutesProvider.ProviderConfigurationError: Provider ids must be lowercase and trimmed.]`,
     )
   })
 })
 
 describe('is', () => {
-  test('requires the funding quote capability', () => {
+  test('requires the route quote capability', () => {
     expect(
-      FundingProvider.is({
+      RoutesProvider.is({
         id: 'incomplete',
         name: 'Incomplete',
-        type: 'funding',
+        type: 'routes',
       }),
     ).toBe(false)
-    expect(FundingProvider.is(providers[0])).toBe(true)
+    expect(RoutesProvider.is(providers[0])).toBe(true)
+  })
+})
+
+describe('canReconcileTransfer', () => {
+  test('requires source and destination verification', () => {
+    expect(RoutesProvider.canReconcileTransfer(Stargate.stargate())).toBe(true)
+    expect(RoutesProvider.canReconcileTransfer(Relay.relay())).toBe(false)
+  })
+})
+
+describe('observe', () => {
+  test('reports successful and failed provider calls without changing their behavior', async () => {
+    const attempts: RoutesProvider.ProviderAttemptResult[] = []
+    const provider = { id: 'relay' }
+    const result = await RoutesProvider.observe(provider, async () => 'value', {
+      onAttempt: (attempt) => attempts.push(attempt),
+      operation: 'listDepositAddressRequests',
+    })
+    const cause = new RoutesProvider.ProviderResponseError(503, null)
+    const rejected = RoutesProvider.observe(
+      provider,
+      async () => {
+        throw cause
+      },
+      {
+        onAttempt: (attempt) => attempts.push(attempt),
+        operation: 'verifyDestinationDelivery',
+      },
+    )
+
+    await expect(rejected).rejects.toBe(cause)
+    expect({
+      attempts: attempts.map(({ durationMs: _durationMs, ...attempt }) => attempt),
+      result,
+    }).toMatchInlineSnapshot(`
+      {
+        "attempts": [
+          {
+            "id": "relay",
+            "operation": "listDepositAddressRequests",
+            "outcome": "success",
+          },
+          {
+            "failure": "http",
+            "id": "relay",
+            "operation": "verifyDestinationDelivery",
+            "outcome": "failed",
+          },
+        ],
+        "result": "value",
+      }
+    `)
+  })
+
+  test('ignores observation callback failures', async () => {
+    await expect(
+      RoutesProvider.observe({ id: 'relay' }, async () => 'value', {
+        onAttempt: () => {
+          throw new Error('metrics unavailable')
+        },
+        operation: 'receiveWebhook',
+      }),
+    ).resolves.toBe('value')
+  })
+})
+
+describe('formatAttempt', () => {
+  test('retains bounded failure details', () => {
+    expect(
+      RoutesProvider.formatAttempt({
+        cause: new RoutesProvider.ProviderTimeoutError(),
+        durationMs: 10,
+        operation: 'verifySourceTransaction',
+        outcome: 'failed',
+        provider: { id: 'stargate' },
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "durationMs": 10,
+        "failure": "timeout",
+        "id": "stargate",
+        "operation": "verifySourceTransaction",
+        "outcome": "failed",
+      }
+    `)
+  })
+
+  test('classifies webhook validation failures as payload failures', () => {
+    expect(
+      [
+        new RoutesProvider.WebhookAuthenticationError(),
+        new RoutesProvider.WebhookPayloadError(),
+      ].map((cause) =>
+        RoutesProvider.formatAttempt({
+          cause,
+          durationMs: 10,
+          operation: 'receiveWebhook',
+          outcome: 'failed',
+          provider: { id: 'relay' },
+        }),
+      ),
+    ).toMatchInlineSnapshot(`
+      [
+        {
+          "durationMs": 10,
+          "failure": "payload",
+          "id": "relay",
+          "operation": "receiveWebhook",
+          "outcome": "failed",
+        },
+        {
+          "durationMs": 10,
+          "failure": "payload",
+          "id": "relay",
+          "operation": "receiveWebhook",
+          "outcome": "failed",
+        },
+      ]
+    `)
   })
 })
 
 describe('getQuotes', () => {
+  test('reports bounded request outcomes and quote ages', async () => {
+    const results: RoutesProvider.QuoteRequestResult[] = []
+    const onResult = (result: RoutesProvider.QuoteRequestResult) => results.push(result)
+    const available = withGetQuote('relay', async () => ({
+      destinationAmount: '990000',
+      sampledAt: new Date(Date.now() - 1_000).toISOString(),
+      status: 'available',
+    }))
+    const unavailable = withGetQuote('relay', async () => ({
+      sampledAt: new Date().toISOString(),
+      status: 'unavailable',
+    }))
+    const failed = withGetQuote('relay', async () => {
+      throw new Error('upstream unavailable')
+    })
+
+    await RoutesProvider.getQuotes({
+      ...baseUsdcRequest,
+      onResult,
+      providers: [available],
+    })
+    await RoutesProvider.getQuotes({
+      ...baseUsdcRequest,
+      onResult,
+      providers: [unavailable],
+    })
+    await RoutesProvider.getQuotes({
+      ...baseUsdcRequest,
+      onResult,
+      provider: undefined,
+      providers: [],
+    })
+    await expect(
+      RoutesProvider.getQuotes({
+        ...baseUsdcRequest,
+        onResult,
+        providers: [failed],
+      }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`[RoutesProvider.ProviderQuoteError]`)
+
+    expect(results).toEqual([
+      {
+        candidateCount: 1,
+        outcome: 'available',
+        quotes: [
+          {
+            ageMs: expect.any(Number),
+            customerValueLossBps: 100,
+            destinationChain: 'eip155:4217',
+            destinationToken: 'eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50',
+            futureSkewMs: 0,
+            provider: 'relay',
+            sourceChain: 'eip155:8453',
+            sourceToken: 'eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+          },
+        ],
+      },
+      { candidateCount: 1, outcome: 'unavailable', quotes: [] },
+      { candidateCount: 0, outcome: 'unsupported', quotes: [] },
+      { candidateCount: 1, outcome: 'failed', quotes: [] },
+    ])
+    expect(results[0]?.quotes[0]?.ageMs).toBeGreaterThanOrEqual(1_000)
+  })
+
+  test('reports provider timestamps ahead of the API clock', async () => {
+    const results: RoutesProvider.QuoteRequestResult[] = []
+    vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00.000Z'), toFake: ['Date'] })
+    try {
+      await RoutesProvider.getQuotes({
+        ...baseUsdcRequest,
+        onResult: (result) => results.push(result),
+        providers: [
+          withGetQuote('relay', async () => ({
+            destinationAmount: '990000',
+            sampledAt: '2026-01-01T00:00:05.000Z',
+            status: 'available',
+          })),
+        ],
+      })
+
+      expect(results[0]?.quotes).toEqual([
+        {
+          ageMs: 0,
+          customerValueLossBps: 100,
+          destinationChain: 'eip155:4217',
+          destinationToken: 'eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50',
+          futureSkewMs: 5_000,
+          provider: 'relay',
+          sourceChain: 'eip155:8453',
+          sourceToken: 'eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+        },
+      ])
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   test('returns normalized successful provider quotes', async () => {
-    const attempts: FundingProvider.ProviderAttempt[] = []
-    let seen: FundingProvider.getQuote.Parameters | undefined
-    const quotes = await FundingProvider.getQuotes({
+    const attempts: RoutesProvider.ProviderAttempt[] = []
+    let seen: RoutesProvider.getQuote.Parameters | undefined
+    const quotes = await RoutesProvider.getQuotes({
       ...baseUsdcRequest,
       onAttempt: (attempt) => attempts.push(attempt),
       providers: [
@@ -132,10 +349,7 @@ describe('getQuotes', () => {
         formatted: '0.98',
       },
       id: 'base-usdc-tempo-usdce-relay',
-      quality: {
-        liquiditySource: 'providerQuote',
-        tier: 'liquid',
-      },
+      quality: { tier: 'liquid' },
       quote: { sampledAt: '2026-01-01T00:00:00Z' },
       sourceAmount: {
         baseUnits: '1000000',
@@ -151,8 +365,8 @@ describe('getQuotes', () => {
   })
 
   test('omits provider-declared unavailable quotes', async () => {
-    const attempts: FundingProvider.ProviderAttempt[] = []
-    const quotes = FundingProvider.getQuotes({
+    const attempts: RoutesProvider.ProviderAttempt[] = []
+    const quotes = RoutesProvider.getQuotes({
       ...baseUsdcRequest,
       onAttempt: (attempt) => attempts.push(attempt),
       providers: [
@@ -170,8 +384,8 @@ describe('getQuotes', () => {
   })
 
   test('rejects provider failures when no quote succeeds', async () => {
-    const attempts: FundingProvider.ProviderAttempt[] = []
-    const quotes = FundingProvider.getQuotes({
+    const attempts: RoutesProvider.ProviderAttempt[] = []
+    const quotes = RoutesProvider.getQuotes({
       ...baseUsdcRequest,
       onAttempt: (attempt) => attempts.push(attempt),
       providers: [
@@ -184,7 +398,7 @@ describe('getQuotes', () => {
     const cause = await quotes.catch((error: unknown) => error)
     expect(cause).toMatchObject({
       failures: [{ cause: expect.any(Error), provider: { id: 'relay' } }],
-      fundingProviderAttempts: [
+      routesProviderAttempts: [
         {
           durationMs: expect.any(Number),
           failure: 'unknown',
@@ -193,7 +407,7 @@ describe('getQuotes', () => {
           outcome: 'failed',
         },
       ],
-      name: 'FundingProvider.ProviderQuoteError',
+      name: 'RoutesProvider.ProviderQuoteError',
       providerFailure: { failure: 'unknown', id: 'relay', operation: 'getQuote' },
     })
     expect(attempts.map(stableAttempt)).toEqual([
@@ -207,8 +421,8 @@ describe('getQuotes', () => {
   })
 
   test('records thin quotes separately from available quotes', async () => {
-    const attempts: FundingProvider.ProviderAttempt[] = []
-    const quotes = await FundingProvider.getQuotes({
+    const attempts: RoutesProvider.ProviderAttempt[] = []
+    const quotes = await RoutesProvider.getQuotes({
       ...baseUsdcRequest,
       onAttempt: (attempt) => attempts.push(attempt),
       providers: [
@@ -227,7 +441,7 @@ describe('getQuotes', () => {
   })
 
   test('rejects successful provider responses without output amounts', async () => {
-    const quotes = FundingProvider.getQuotes({
+    const quotes = RoutesProvider.getQuotes({
       ...baseUsdcRequest,
       providers: [
         withGetQuote('relay', async () => ({
@@ -238,12 +452,12 @@ describe('getQuotes', () => {
     })
 
     await expect(quotes).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[FundingProvider.ProviderQuoteError]`,
+      `[RoutesProvider.ProviderQuoteError]`,
     )
   })
 
   test('rejects provider responses outside the shared schema', async () => {
-    const quotes = FundingProvider.getQuotes({
+    const quotes = RoutesProvider.getQuotes({
       ...baseUsdcRequest,
       providers: [
         withGetQuote(
@@ -270,7 +484,7 @@ describe('getQuotes', () => {
   ])(
     'rejects invalid successful amounts %#',
     async ({ destinationAmountMin, destinationAmount }) => {
-      const quotes = FundingProvider.getQuotes({
+      const quotes = RoutesProvider.getQuotes({
         ...baseUsdcRequest,
         providers: [
           withGetQuote('relay', async () => ({
@@ -291,7 +505,7 @@ describe('getQuotes', () => {
   test('allows provider quotes within the default deadline', async () => {
     vi.useFakeTimers()
     try {
-      const quotes = FundingProvider.getQuotes({
+      const quotes = RoutesProvider.getQuotes({
         ...baseUsdcRequest,
         providers: [
           withGetQuote(
@@ -321,9 +535,9 @@ describe('getQuotes', () => {
   })
 
   test('aborts providers that exceed the quote deadline', async () => {
-    const attempts: FundingProvider.ProviderAttempt[] = []
+    const attempts: RoutesProvider.ProviderAttempt[] = []
     let aborted = false
-    const quotes = FundingProvider.getQuotes({
+    const quotes = RoutesProvider.getQuotes({
       ...baseUsdcRequest,
       providerTimeoutMs: 1,
       providers: [
@@ -331,19 +545,19 @@ describe('getQuotes', () => {
           signal.addEventListener('abort', () => {
             aborted = true
           })
-          return new Promise<FundingProvider.getQuote.ReturnType>(() => {})
+          return new Promise<RoutesProvider.getQuote.ReturnType>(() => {})
         }),
       ],
       onAttempt: (attempt) => attempts.push(attempt),
     })
 
     await expect(quotes).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[FundingProvider.ProviderQuoteError]`,
+      `[RoutesProvider.ProviderQuoteError]`,
     )
     expect(aborted).toBe(true)
     expect(attempts.map(stableAttempt)).toEqual([
       {
-        cause: expect.any(FundingProvider.ProviderTimeoutError),
+        cause: expect.any(RoutesProvider.ProviderTimeoutError),
         operation: 'getQuote',
         outcome: 'failed',
         provider: 'relay',
@@ -352,8 +566,8 @@ describe('getQuotes', () => {
   })
 
   test('passes cache policy through to providers', async () => {
-    let seen: FundingProvider.getQuote.Parameters | undefined
-    await FundingProvider.getQuotes({
+    let seen: RoutesProvider.getQuote.Parameters | undefined
+    await RoutesProvider.getQuotes({
       ...baseUsdcRequest,
       cache: { bypass: true },
       providers: [
@@ -368,8 +582,8 @@ describe('getQuotes', () => {
   })
 
   test('returns successful quotes when another provider fails', async () => {
-    const attempts: FundingProvider.ProviderAttempt[] = []
-    const quotes = await FundingProvider.getQuotes({
+    const attempts: RoutesProvider.ProviderAttempt[] = []
+    const quotes = await RoutesProvider.getQuotes({
       ...baseUsdcRequest,
       onAttempt: (attempt) => attempts.push(attempt),
       provider: undefined,
@@ -398,7 +612,7 @@ describe('getQuotes', () => {
     ])
   })
 
-  test('does not let attempt observers change quote outcomes', async () => {
+  test('does not let observers change quote outcomes', async () => {
     const providers_success = [
       withGetQuote('relay', async () => ({
         destinationAmount: '990000',
@@ -407,46 +621,52 @@ describe('getQuotes', () => {
       })),
     ]
     await expect(
-      FundingProvider.getQuotes({
+      RoutesProvider.getQuotes({
         ...baseUsdcRequest,
         onAttempt() {
           throw new Error('observer failed')
         },
+        onResult() {
+          throw new Error('observer failed')
+        },
         providers: providers_success,
       }),
     ).resolves.toHaveLength(1)
 
     await expect(
-      FundingProvider.getQuotes({
+      RoutesProvider.getQuotes({
         ...baseUsdcRequest,
         onAttempt() {
           throw new Error('observer failed')
         },
+        onResult() {
+          throw new Error('observer failed')
+        },
         providers: [
           withGetQuote('relay', async () => {
             throw new Error('provider failed')
           }),
         ],
       }),
-    ).rejects.toThrowErrorMatchingInlineSnapshot(`[FundingProvider.ProviderQuoteError]`)
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`[RoutesProvider.ProviderQuoteError]`)
   })
 })
 
 describe('createDepositAddress', () => {
   test('rejects invalid base-unit amounts', async () => {
     await expect(
-      FundingProvider.createDepositAddress({
+      RoutesProvider.createDepositAddress({
         ...depositAddressOptions,
         amount: '10.5',
         providers: [withCreateDepositAddress('relay', async () => depositAddressResult())],
       }),
-    ).rejects.toThrowErrorMatchingInlineSnapshot(`[FundingProvider.InvalidAmountError]`)
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`[RoutesProvider.InvalidAmountError]`)
   })
 
   test('provisions one deterministic capability-enabled candidate', async () => {
-    const attempts: FundingProvider.ProviderAttempt[] = []
-    let seen: FundingProvider.createDepositAddress.Parameters | undefined
-    const selection = await FundingProvider.createDepositAddress({
+    const attempts: RoutesProvider.ProviderAttempt[] = []
+    let seen: RoutesProvider.createDepositAddress.Parameters | undefined
+    const selection = await RoutesProvider.createDepositAddress({
       ...depositAddressOptions,
       onAttempt: (attempt) => attempts.push(attempt),
       providers: [
@@ -489,14 +709,14 @@ describe('createDepositAddress', () => {
   })
 
   test('returns no selection when the provider reports no route', async () => {
-    const attempts: FundingProvider.ProviderAttempt[] = []
+    const attempts: RoutesProvider.ProviderAttempt[] = []
     await expect(
-      FundingProvider.createDepositAddress({
+      RoutesProvider.createDepositAddress({
         ...depositAddressOptions,
         onAttempt: (attempt) => attempts.push(attempt),
         providers: [
           withCreateDepositAddress('relay', async () => {
-            throw new FundingProvider.ProviderUnavailableError()
+            throw new RoutesProvider.ProviderUnavailableError()
           }),
         ],
       }),
@@ -508,7 +728,7 @@ describe('createDepositAddress', () => {
 
   test('rejects malformed provider responses', async () => {
     await expect(
-      FundingProvider.createDepositAddress({
+      RoutesProvider.createDepositAddress({
         ...depositAddressOptions,
         providers: [
           withCreateDepositAddress('relay', async () => ({
@@ -528,7 +748,7 @@ describe('createDepositAddress', () => {
 
   test('rejects provider addresses that do not match the source chain', async () => {
     await expect(
-      FundingProvider.createDepositAddress({
+      RoutesProvider.createDepositAddress({
         ...depositAddressOptions,
         providers: [
           withCreateDepositAddress('relay', async () => ({
@@ -544,7 +764,7 @@ describe('createDepositAddress', () => {
 
   test('rejects provider minimums above the estimated destination amount', async () => {
     await expect(
-      FundingProvider.createDepositAddress({
+      RoutesProvider.createDepositAddress({
         ...depositAddressOptions,
         providers: [
           withCreateDepositAddress('relay', async () => ({
@@ -560,7 +780,7 @@ describe('createDepositAddress', () => {
 
   test('rejects expired provider terms', async () => {
     await expect(
-      FundingProvider.createDepositAddress({
+      RoutesProvider.createDepositAddress({
         ...depositAddressOptions,
         providers: [
           withCreateDepositAddress('relay', async () => ({
@@ -576,7 +796,7 @@ describe('createDepositAddress', () => {
 
   test('rejects invalid refund addresses before calling the provider', async () => {
     await expect(
-      FundingProvider.createDepositAddress({
+      RoutesProvider.createDepositAddress({
         ...depositAddressOptions,
         providers: [
           withCreateDepositAddress('relay', async () => {
@@ -585,7 +805,7 @@ describe('createDepositAddress', () => {
         ],
         refundAddress: `0x${'11'.repeat(20)}`,
       }),
-    ).rejects.toThrowErrorMatchingInlineSnapshot(`[FundingProvider.InvalidRefundAddressError]`)
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`[RoutesProvider.InvalidRefundAddressError]`)
   })
 })
 
@@ -651,9 +871,9 @@ describe('getDepositAddressCandidates', () => {
 
     expect(
       routes.map((route) => {
-        const candidate = FundingProvider.getDepositAddressCandidates({
+        const candidate = RoutesProvider.getDepositAddressCandidates({
           ...route,
-          catalog: TestFunding.snapshot,
+          catalog: TestRoutes.snapshot,
           destinationChainId: 4217,
           providers: [providers[1]!],
         })[0]?.candidate
@@ -727,19 +947,19 @@ describe('getDepositAddressCandidates', () => {
   })
 
   test('requires both catalog and provider capability', () => {
-    const quoteOnly = FundingProvider.from({
+    const quoteOnly = RoutesProvider.from({
       getQuote: (input, signal) => providers[1]!.getQuote(input, signal),
       id: 'relay',
       name: 'Relay',
     })
     expect(
-      FundingProvider.getDepositAddressCandidates({
+      RoutesProvider.getDepositAddressCandidates({
         ...depositAddressOptions,
         providers: [quoteOnly],
       }),
     ).toEqual([])
     expect(
-      FundingProvider.getDepositAddressCandidates({
+      RoutesProvider.getDepositAddressCandidates({
         ...depositAddressOptions,
         providers: [providers[1]!],
       }),
@@ -748,8 +968,21 @@ describe('getDepositAddressCandidates', () => {
 })
 
 describe('prepareTransfer', () => {
+  test.each([
+    ['recipient', { recipient: 'invalid' }, 'RoutesProvider.InvalidRecipientAddressError'],
+    ['sender', { sender: 'invalid' }, 'RoutesProvider.InvalidSenderAddressError'],
+  ] as const)('validates the %s against its route chain', async (_field, input, name) => {
+    await expect(
+      RoutesProvider.prepareTransfer({
+        ...prepareOptions,
+        ...input,
+        providers: [withPrepareTransfer('relay', async () => preparedResult())],
+      }),
+    ).rejects.toMatchObject({ name })
+  })
+
   test('validates preparation results at the provider boundary', async () => {
-    const transfer = FundingProvider.prepareTransfer({
+    const transfer = RoutesProvider.prepareTransfer({
       ...prepareOptions,
       providers: [
         withPrepareTransfer(
@@ -760,14 +993,18 @@ describe('prepareTransfer', () => {
     })
 
     await expect(transfer).rejects.toMatchObject({
-      providerFailure: { failure: 'payload', id: 'relay', operation: 'prepareTransfer' },
+      providerFailure: {
+        failure: 'payload',
+        id: 'relay',
+        operation: 'prepareTransfer',
+      },
     })
   })
 
   test('enforces provider-style slippage rounding', async () => {
-    const inputs: FundingProvider.prepareTransfer.Parameters[] = []
+    const inputs: RoutesProvider.prepareTransfer.Parameters[] = []
     const prepare = (destinationAmountMin: string) =>
-      FundingProvider.prepareTransfer({
+      RoutesProvider.prepareTransfer({
         ...prepareOptions,
         providers: [
           withPrepareTransfer('relay', async (input) => {
@@ -786,6 +1023,8 @@ describe('prepareTransfer', () => {
       providerFailure: { failure: 'payload', id: 'relay', operation: 'prepareTransfer' },
     })
     await expect(prepare('9999')).resolves.toMatchObject({
+      bestDestinationAmount: '10001',
+      preparedCount: 1,
       result: { destinationAmount: '10001', destinationAmountMin: '9999' },
     })
     await expect(prepare('10000')).resolves.toMatchObject({
@@ -802,7 +1041,7 @@ describe('prepareTransfer', () => {
     vi.setSystemTime(new Date('2026-01-01T00:01:00.000Z'))
     try {
       await expect(
-        FundingProvider.prepareTransfer({
+        RoutesProvider.prepareTransfer({
           ...prepareOptions,
           providers: [
             withPrepareTransfer('relay', async () => ({ ...preparedResult(), ...quote })),
@@ -817,14 +1056,14 @@ describe('prepareTransfer', () => {
   })
 
   test('returns no selection when every provider confirms unavailability', async () => {
-    const attempts: FundingProvider.ProviderAttempt[] = []
+    const attempts: RoutesProvider.ProviderAttempt[] = []
     await expect(
-      FundingProvider.prepareTransfer({
+      RoutesProvider.prepareTransfer({
         ...prepareOptions,
         onAttempt: (attempt) => attempts.push(attempt),
         providers: [
           withPrepareTransfer('relay', async () => {
-            throw new FundingProvider.ProviderUnavailableError()
+            throw new RoutesProvider.ProviderUnavailableError()
           }),
         ],
       }),
@@ -837,7 +1076,7 @@ describe('prepareTransfer', () => {
   test('accepts preparations without correlation', async () => {
     const { correlation: _correlation, ...result } = preparedResult()
     const spender = `0x${'44'.repeat(20)}`
-    const selected = FundingProvider.prepareTransfer({
+    const selected = RoutesProvider.prepareTransfer({
       ...prepareOptions,
       providers: [
         withPrepareTransfer('relay', async () => {
@@ -864,24 +1103,72 @@ describe('prepareTransfer', () => {
 })
 
 describe('getPrepareCandidates', () => {
+  test('selects Tempo as the source for an outbound destination chain', () => {
+    const inbound = TestRoutes.data.routes.find(
+      (route) =>
+        route.providerId === 'stargate' &&
+        route.sourceChainId === 'eip155:8453' &&
+        route.sourceTokenId === 'usdc' &&
+        route.destinationTokenId === 'usdce' &&
+        route.capabilities?.transfer,
+    )!
+    const catalog = RoutesCatalog.compile({
+      catalog: {
+        id: 'default',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+        version: 'outbound-transfer',
+      },
+      ...TestRoutes.data,
+      routes: [
+        ...TestRoutes.data.routes,
+        {
+          ...inbound,
+          destinationChainId: inbound.sourceChainId,
+          destinationTokenId: inbound.sourceTokenId,
+          sourceChainId: inbound.destinationChainId,
+          sourceTokenId: inbound.destinationTokenId,
+        },
+      ],
+    })
+
+    const [selected] = RoutesProvider.getPrepareCandidates({
+      catalog,
+      destinationChain: 'base',
+      destinationToken: 'USDC',
+      method: 'transaction',
+      mode: 'exactSource',
+      providers: [withPrepareTransfer('stargate', async () => preparedResult())],
+      sourceAmount: '1000000',
+      sourceChain: 'tempo',
+      sourceToken: 'USDC.e',
+    })
+
+    expect(selected?.candidate).toMatchObject({
+      destinationChain: { id: 'eip155:8453' },
+      destinationToken: { symbol: 'USDC' },
+      sourceChain: { id: 'eip155:4217' },
+      sourceToken: { symbol: 'USDC.e' },
+    })
+  })
+
   test('restricts candidates to the requested provider', () => {
     const relay = withPrepareTransfer('relay', async () => preparedResult())
     const stargate = withPrepareTransfer('stargate', async () => preparedResult())
-    const route = TestFunding.data.routes.find(
+    const route = TestRoutes.data.routes.find(
       (entry) => entry.providerId === 'relay' && entry.capabilities?.transfer,
     )!
-    const catalog = FundingCatalog.compile({
+    const catalog = RoutesCatalog.compile({
       catalog: {
         id: 'default',
         updatedAt: '2026-01-01T00:00:00.000Z',
         version: 'test',
       },
-      ...TestFunding.data,
-      routes: [...TestFunding.data.routes, { ...route, providerId: 'stargate' }],
+      ...TestRoutes.data,
+      routes: [...TestRoutes.data.routes, { ...route, providerId: 'stargate' }],
     })
 
     expect(
-      FundingProvider.getPrepareCandidates({
+      RoutesProvider.getPrepareCandidates({
         ...prepareOptions,
         catalog,
         provider: 'stargate',
@@ -893,30 +1180,30 @@ describe('getPrepareCandidates', () => {
   test('restricts candidates to the selected destination chain', () => {
     const provider = withPrepareTransfer('relay', async () => preparedResult())
     expect(
-      FundingProvider.getPrepareCandidates({
+      RoutesProvider.getPrepareCandidates({
         ...prepareOptions,
-        destinationChainId: 4217,
+        destinationChain: 'tempo',
         providers: [provider],
       }),
     ).toHaveLength(1)
-    expect(
-      FundingProvider.getPrepareCandidates({
+    expect(() =>
+      RoutesProvider.getPrepareCandidates({
         ...prepareOptions,
-        destinationChainId: 421700001,
+        destinationChain: 'eip155:421700001',
         providers: [provider],
       }),
-    ).toEqual([])
+    ).toThrowErrorMatchingInlineSnapshot(`[RoutesProvider.UnsupportedDestinationChainError]`)
   })
 
   test('uses transfer modes without treating deposit addresses as transfers', () => {
-    const catalog = FundingCatalog.compile({
+    const catalog = RoutesCatalog.compile({
       catalog: {
         id: 'default',
         updatedAt: '2026-01-01T00:00:00.000Z',
         version: 'test',
       },
-      ...TestFunding.data,
-      routes: TestFunding.data.routes.map((route) =>
+      ...TestRoutes.data,
+      routes: TestRoutes.data.routes.map((route) =>
         route.capabilities
           ? {
               ...route,
@@ -930,7 +1217,7 @@ describe('getPrepareCandidates', () => {
     })
     const provider = withPrepareTransfer('relay', async () => preparedResult())
     const candidates = (mode: 'exactDestination' | 'exactSource') =>
-      FundingProvider.getPrepareCandidates({
+      RoutesProvider.getPrepareCandidates({
         ...prepareOptions,
         catalog,
         mode,
@@ -940,19 +1227,19 @@ describe('getPrepareCandidates', () => {
     expect(candidates('exactDestination')).toHaveLength(1)
     expect(candidates('exactSource')).toEqual([])
 
-    const depositAddressOnly = FundingCatalog.compile({
+    const depositAddressOnly = RoutesCatalog.compile({
       catalog: {
         id: 'default',
         updatedAt: '2026-01-01T00:00:00.000Z',
         version: 'test',
       },
-      ...TestFunding.data,
-      routes: TestFunding.data.routes.map((route) =>
+      ...TestRoutes.data,
+      routes: TestRoutes.data.routes.map((route) =>
         route.capabilities ? { ...route, capabilities: { depositAddress: true } } : route,
       ),
     })
     expect(
-      FundingProvider.getPrepareCandidates({
+      RoutesProvider.getPrepareCandidates({
         ...prepareOptions,
         catalog: depositAddressOnly,
         providers: [provider],
@@ -961,21 +1248,21 @@ describe('getPrepareCandidates', () => {
   })
 })
 
-function stableAttempt(attempt: FundingProvider.ProviderAttempt) {
+function stableAttempt(attempt: RoutesProvider.ProviderAttempt) {
   const { durationMs: _durationMs, provider, ...rest } = attempt
   return { ...rest, provider: provider.id }
 }
 
 function withGetQuote(
-  id: FundingProvider.ProviderId,
-  getQuote: FundingProvider.Provider['getQuote'],
+  id: RoutesProvider.ProviderId,
+  getQuote: RoutesProvider.Provider['getQuote'],
 ) {
   const provider = providers.find((entry) => entry.id === id)
   if (!provider) throw new Error(`Missing ${id} provider`)
-  return FundingProvider.from({ ...provider, getQuote })
+  return RoutesProvider.from({ ...provider, getQuote })
 }
 
-function depositAddressResult(): FundingProvider.createDepositAddress.ReturnType {
+function depositAddressResult(): RoutesProvider.createDepositAddress.ReturnType {
   return {
     address: 'TJRabPrwbZy45sbavfcjinPJC18kjpRTv8',
     correlation: { requestId: 'request_1' },
@@ -987,15 +1274,15 @@ function depositAddressResult(): FundingProvider.createDepositAddress.ReturnType
 }
 
 function withCreateDepositAddress(
-  id: FundingProvider.ProviderId,
-  createDepositAddress: NonNullable<FundingProvider.Provider['createDepositAddress']>,
+  id: RoutesProvider.ProviderId,
+  createDepositAddress: NonNullable<RoutesProvider.Provider['createDepositAddress']>,
 ) {
   const provider = providers.find((entry) => entry.id === id)
   if (!provider) throw new Error(`Missing ${id} provider`)
-  return FundingProvider.from({ ...provider, createDepositAddress })
+  return RoutesProvider.from({ ...provider, createDepositAddress })
 }
 
-function preparedResult(): FundingProvider.prepareTransfer.ReturnType {
+function preparedResult(): RoutesProvider.prepareTransfer.ReturnType {
   return {
     action: {
       calls: [{ data: '0xe8017952', to: `0x${'44'.repeat(20)}`, value: '0x0' }],
@@ -1010,17 +1297,17 @@ function preparedResult(): FundingProvider.prepareTransfer.ReturnType {
 }
 
 function withPrepareTransfer(
-  id: FundingProvider.ProviderId,
-  prepareTransfer: NonNullable<FundingProvider.Provider['prepareTransfer']>,
+  id: RoutesProvider.ProviderId,
+  prepareTransfer: NonNullable<RoutesProvider.Provider['prepareTransfer']>,
 ) {
   const provider = providers.find((entry) => entry.id === id)
   if (!provider) throw new Error(`Missing ${id} provider`)
-  return FundingProvider.from({ ...provider, prepareTransfer })
+  return RoutesProvider.from({ ...provider, prepareTransfer })
 }
 
 describe('getChains', () => {
   test('derives custom chain and token inventory from provider routes', () => {
-    const catalog = FundingCatalog.compile({
+    const catalog = RoutesCatalog.compile({
       catalog: {
         id: 'default',
         updatedAt: '2026-01-01T00:00:00.000Z',
@@ -1086,7 +1373,7 @@ describe('getChains', () => {
         },
       ],
     })
-    const provider = FundingProvider.from({
+    const provider = RoutesProvider.from({
       id: 'custom',
       name: 'Custom',
       async getQuote() {
@@ -1094,7 +1381,7 @@ describe('getChains', () => {
       },
     })
 
-    expect(FundingProvider.getChains({ catalog, providers: [provider] })).toMatchInlineSnapshot(`
+    expect(RoutesProvider.getChains({ catalog, providers: [provider] })).toMatchInlineSnapshot(`
       [
         {
           "addressFormat": "hex",
@@ -1120,7 +1407,7 @@ describe('getChains', () => {
 
   test('returns only chain and token inputs with quote inventory', () => {
     expect(
-      FundingProvider.getChains({ catalog: TestFunding.snapshot, providers }).map(
+      RoutesProvider.getChains({ catalog: TestRoutes.snapshot, providers }).map(
         (chain) => chain.id,
       ),
     ).toEqual([
@@ -1130,11 +1417,12 @@ describe('getChains', () => {
       'eip155:137',
       'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
       'tron:0x2b6653dc',
+      'eip155:4217',
     ])
   })
 
   test('uses chain-specific token keys for non-EVM inventory', () => {
-    const chains = FundingProvider.getChains({ catalog: TestFunding.snapshot, providers })
+    const chains = RoutesProvider.getChains({ catalog: TestRoutes.snapshot, providers })
     expect(chains.find((chain) => chain.kind === 'solana')?.tokens[0]?.tokenKey).toBe(
       'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
     )
@@ -1145,18 +1433,66 @@ describe('getChains', () => {
 })
 
 describe('getQuoteCandidates', () => {
+  test('selects Tempo as the source for an outbound destination chain', () => {
+    const inbound = TestRoutes.data.routes.find(
+      (route) =>
+        route.providerId === 'relay' &&
+        route.sourceChainId === 'eip155:8453' &&
+        route.sourceTokenId === 'usdc' &&
+        route.destinationTokenId === 'usdce',
+    )!
+    const catalog = RoutesCatalog.compile({
+      catalog: {
+        id: 'default',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+        version: 'outbound',
+      },
+      ...TestRoutes.data,
+      routes: [
+        ...TestRoutes.data.routes,
+        {
+          ...inbound,
+          destinationChainId: inbound.sourceChainId,
+          destinationTokenId: inbound.sourceTokenId,
+          sourceChainId: inbound.destinationChainId,
+          sourceTokenId: inbound.destinationTokenId,
+        },
+      ],
+    })
+
+    const [candidate] = RoutesProvider.getQuoteCandidates({
+      catalog,
+      destinationChain: 'base',
+      destinationToken: 'USDC',
+      provider: 'relay',
+      providers,
+      sourceAmount: '1000000',
+      sourceAmountUnits: 'baseUnits',
+      sourceChain: 'tempo',
+      sourceToken: 'USDC.e',
+    })
+
+    expect(candidate).toMatchObject({
+      destinationChain: { id: 'eip155:8453' },
+      destinationToken: { symbol: 'USDC' },
+      id: 'tempo-usdce-base-usdc-relay',
+      sourceChain: { id: 'eip155:4217' },
+      sourceToken: { symbol: 'USDC.e' },
+    })
+  })
+
   test('validates base-unit syntax without configured providers', () => {
     expect(() =>
-      FundingProvider.getQuoteCandidates({
+      RoutesProvider.getQuoteCandidates({
         ...baseUsdcRequest,
         providers: [],
         sourceAmount: '1.5',
       }),
-    ).toThrowErrorMatchingInlineSnapshot(`[FundingProvider.InvalidAmountError]`)
+    ).toThrowErrorMatchingInlineSnapshot(`[RoutesProvider.InvalidAmountError]`)
   })
 
   test('converts decimal source amounts with token precision', () => {
-    const [candidate] = FundingProvider.getQuoteCandidates({
+    const [candidate] = RoutesProvider.getQuoteCandidates({
       ...baseUsdcRequest,
       sourceAmount: '1.25',
       sourceAmountUnits: 'decimal',
@@ -1167,7 +1503,7 @@ describe('getQuoteCandidates', () => {
   })
 
   test('carries provider route configuration without duplicating token metadata', () => {
-    const [candidate] = FundingProvider.getQuoteCandidates({
+    const [candidate] = RoutesProvider.getQuoteCandidates({
       ...baseUsdcRequest,
       provider: 'stargate',
       providers,
@@ -1180,20 +1516,20 @@ describe('getQuoteCandidates', () => {
   })
 
   test('resolves normalized catalog aliases', () => {
-    const catalog = FundingCatalog.compile({
+    const catalog = RoutesCatalog.compile({
       catalog: {
         id: 'default',
         updatedAt: '2026-01-01T00:00:00.000Z',
         version: 'aliases',
       },
-      ...TestFunding.data,
-      chains: TestFunding.data.chains.map((chain) =>
+      ...TestRoutes.data,
+      chains: TestRoutes.data.chains.map((chain) =>
         chain.id === 'eip155:56' ? { ...chain, aliases: ['BSC'] } : chain,
       ),
     })
 
     expect(
-      FundingProvider.getQuoteCandidates({
+      RoutesProvider.getQuoteCandidates({
         ...baseUsdcRequest,
         catalog,
         providers,
@@ -1204,15 +1540,15 @@ describe('getQuoteCandidates', () => {
 
   test('uses canonical token slugs in quote ids', () => {
     const bridgedAddress = '0x1111111111111111111111111111111111111111'
-    const catalog = FundingCatalog.compile({
+    const catalog = RoutesCatalog.compile({
       catalog: {
         id: 'default',
         updatedAt: '2026-01-01T00:00:00.000Z',
         version: 'duplicate-symbols',
       },
-      ...TestFunding.data,
+      ...TestRoutes.data,
       chainTokens: [
-        ...TestFunding.data.chainTokens,
+        ...TestRoutes.data.chainTokens,
         {
           address: bridgedAddress,
           chainId: 'eip155:8453',
@@ -1223,7 +1559,7 @@ describe('getQuoteCandidates', () => {
         },
       ],
       routes: [
-        ...TestFunding.data.routes,
+        ...TestRoutes.data.routes,
         {
           destinationChainId: 'eip155:4217',
           destinationTokenId: 'usdce',
@@ -1233,7 +1569,7 @@ describe('getQuoteCandidates', () => {
         },
       ],
       tokens: [
-        ...TestFunding.data.tokens,
+        ...TestRoutes.data.tokens,
         {
           currency: 'USD',
           id: 'usdc-bridged',
@@ -1243,15 +1579,15 @@ describe('getQuoteCandidates', () => {
       ],
     })
     const ids = [
-      FundingProvider.getQuoteCandidates({
+      RoutesProvider.getQuoteCandidates({
         ...baseUsdcRequest,
         catalog,
         providers,
-        sourceToken: TestFunding.data.chainTokens.find(
+        sourceToken: TestRoutes.data.chainTokens.find(
           (token) => token.chainId === 'eip155:8453' && token.tokenId === 'usdc',
         )!.address,
       })[0]?.id,
-      FundingProvider.getQuoteCandidates({
+      RoutesProvider.getQuoteCandidates({
         ...baseUsdcRequest,
         catalog,
         providers,
@@ -1264,18 +1600,18 @@ describe('getQuoteCandidates', () => {
 
   test('rejects decimal source amounts beyond token precision', () => {
     expect(() =>
-      FundingProvider.getQuoteCandidates({
+      RoutesProvider.getQuoteCandidates({
         ...baseUsdcRequest,
         sourceAmount: '1.0000001',
         sourceAmountUnits: 'decimal',
         providers,
       }),
-    ).toThrowErrorMatchingInlineSnapshot(`[FundingProvider.InvalidAmountError]`)
+    ).toThrowErrorMatchingInlineSnapshot(`[RoutesProvider.InvalidAmountError]`)
   })
 
   test('round-trips the advertised Solana chain and token ids', () => {
-    const [candidate] = FundingProvider.getQuoteCandidates({
-      catalog: TestFunding.snapshot,
+    const [candidate] = RoutesProvider.getQuoteCandidates({
+      catalog: TestRoutes.snapshot,
       providers,
       provider: 'rhino',
       sourceAmount: '1000000',
@@ -1290,8 +1626,8 @@ describe('getQuoteCandidates', () => {
 
   test('keeps non-EVM token identifiers case-sensitive', () => {
     expect(
-      FundingProvider.getQuoteCandidates({
-        catalog: TestFunding.snapshot,
+      RoutesProvider.getQuoteCandidates({
+        catalog: TestRoutes.snapshot,
         providers,
         provider: 'rhino',
         sourceAmount: '1000000',
@@ -1303,8 +1639,8 @@ describe('getQuoteCandidates', () => {
   })
 
   test('resolves the complete Tron token key', () => {
-    const [candidate] = FundingProvider.getQuoteCandidates({
-      catalog: TestFunding.snapshot,
+    const [candidate] = RoutesProvider.getQuoteCandidates({
+      catalog: TestRoutes.snapshot,
       providers,
       destinationToken: 'USDT0',
       provider: 'rhino',
@@ -1319,8 +1655,8 @@ describe('getQuoteCandidates', () => {
 
   test('selects proven Squid stablecoin corridors', () => {
     const candidates = [
-      FundingProvider.getQuoteCandidates({
-        catalog: TestFunding.snapshot,
+      RoutesProvider.getQuoteCandidates({
+        catalog: TestRoutes.snapshot,
         providers,
         destinationToken: 'USDC.e',
         provider: 'squid',
@@ -1329,8 +1665,8 @@ describe('getQuoteCandidates', () => {
         sourceChain: 'base',
         sourceToken: 'USDC',
       })[0],
-      FundingProvider.getQuoteCandidates({
-        catalog: TestFunding.snapshot,
+      RoutesProvider.getQuoteCandidates({
+        catalog: TestRoutes.snapshot,
         providers,
         destinationToken: 'USDT0',
         provider: 'squid',
@@ -1349,8 +1685,8 @@ describe('getQuoteCandidates', () => {
 
   test('selects proven Symbiosis stablecoin corridors', () => {
     const candidates = [
-      FundingProvider.getQuoteCandidates({
-        catalog: TestFunding.snapshot,
+      RoutesProvider.getQuoteCandidates({
+        catalog: TestRoutes.snapshot,
         providers,
         destinationToken: 'USDC.e',
         provider: 'symbiosis',
@@ -1359,8 +1695,8 @@ describe('getQuoteCandidates', () => {
         sourceChain: 'base',
         sourceToken: 'USDC',
       })[0],
-      FundingProvider.getQuoteCandidates({
-        catalog: TestFunding.snapshot,
+      RoutesProvider.getQuoteCandidates({
+        catalog: TestRoutes.snapshot,
         providers,
         destinationToken: 'USDT0',
         provider: 'symbiosis',
@@ -1369,8 +1705,8 @@ describe('getQuoteCandidates', () => {
         sourceChain: 'ethereum',
         sourceToken: 'USDT',
       })[0],
-      FundingProvider.getQuoteCandidates({
-        catalog: TestFunding.snapshot,
+      RoutesProvider.getQuoteCandidates({
+        catalog: TestRoutes.snapshot,
         providers,
         destinationToken: 'USDT0',
         provider: 'symbiosis',
@@ -1391,7 +1727,7 @@ describe('getQuoteCandidates', () => {
 
 describe('getProviders', () => {
   test('lists supplied providers', () => {
-    expect(FundingProvider.getProviders({ catalog: TestFunding.snapshot, providers }))
+    expect(RoutesProvider.getProviders({ catalog: TestRoutes.snapshot, providers }))
       .toMatchInlineSnapshot(`
       [
         {
@@ -1423,19 +1759,19 @@ describe('getProviders', () => {
   })
 
   test('ignores routes for unregistered provider ids', () => {
-    const catalog = FundingCatalog.compile({
+    const catalog = RoutesCatalog.compile({
       catalog: {
         id: 'default',
         updatedAt: '2026-01-01T00:00:00.000Z',
         version: 'test',
       },
-      ...TestFunding.data,
-      routes: [{ ...TestFunding.data.routes[0]!, providerId: 'unknown' }],
+      ...TestRoutes.data,
+      routes: [{ ...TestRoutes.data.routes[0]!, providerId: 'unknown' }],
     })
 
     expect({
-      chains: FundingProvider.getChains({ catalog, providers: [providers[1]!] }),
-      providers: FundingProvider.getProviders({ catalog, providers: [providers[1]!] }),
+      chains: RoutesProvider.getChains({ catalog, providers: [providers[1]!] }),
+      providers: RoutesProvider.getProviders({ catalog, providers: [providers[1]!] }),
     }).toEqual({ chains: [], providers: [] })
   })
 })