tapimo 0.14.0 → 0.15.0

package/src/internal/{funding → routes}/providers/relay.ts

@@ -3,20 +3,22 @@ import { getBlockNumber, getLogs, getTransaction, getTransactionReceipt } from '
 import * as z from 'zod/mini'
 
 import * as Db from '../../../db/Db.js'
-import * as FundingDepositAddresses from '../../../db/tables/fundingDepositAddresses.js'
-import * as FundingDepositRequestObservations from '../../../db/tables/fundingDepositRequestObservations.js'
+import * as RoutesDepositAddresses from '../../../db/tables/routesDepositAddresses.js'
+import * as RoutesDepositRequestObservations from '../../../db/tables/routesDepositRequestObservations.js'
+import * as Value from '../../Value.js'
 import * as Viem from '../../Viem.js'
-import * as FundingCatalog from '../Catalog.js'
-import * as FundingChain from '../Chain.js'
+import * as RoutesCatalog from '../Catalog.js'
+import * as RoutesChain from '../Chain.js'
 import * as Evidence from '../Evidence.js'
-import * as FundingProvider from '../Provider.js'
+import * as RoutesProvider from '../Provider.js'
 import * as Subsidy from '../Subsidy.js'
 
 const defaultBaseUrl = 'https://api.relay.link'
-const defaultFetch: FundingProvider.Fetch = (input, init) => globalThis.fetch(input, init)
+const defaultFetch: RoutesProvider.Fetch = (input, init) => globalThis.fetch(input, init)
 const deliveryBackfillBlocks = 256n
 const relayChainsCacheTtlMs = 60_000
 const relayRefundStatuses = ['refund', 'refunded'] as const
+const relayRequestPageLimit = 100
 const sourceSweepForwardBlocks = 256n
 const depositErc20FullAllowance = AbiFunction.from(
   'function depositErc20(address depositor,address token,bytes32 id)',
@@ -147,12 +149,12 @@ namespace schema {
           z.object({
             v2: z.optional(
               z.object({
-                depository: z.string().check(z.regex(/^0x[0-9a-fA-F]{40}$/)),
+                depository: z.string().check(z.minLength(1)),
               }),
             ),
           }),
         ),
-        solverAddresses: z.optional(z.array(z.string().check(z.regex(/^0x[0-9a-fA-F]{40}$/)))),
+        solverAddresses: z.optional(z.array(z.string().check(z.minLength(1)))),
       }),
     ),
   })
@@ -175,8 +177,9 @@ namespace schema {
     }),
   })
 
+  // Relay can publish output entries before assigning their transaction hashes.
   const RequestTransaction = z.object({
-    txHash: z.string().check(z.minLength(1)),
+    txHash: z.optional(z.nullable(z.string())),
   })
 
   export const Requests = z.object({
@@ -186,6 +189,21 @@ namespace schema {
         createdAt: z.iso.datetime(),
         data: z.optional(
           z.object({
+            feeSponsorship: z.optional(
+              z.object({
+                actual: z.optional(
+                  z.object({
+                    sponsorPayment: z.optional(
+                      z.object({
+                        address: z.string().check(z.minLength(1)),
+                        amount: z.string().check(z.regex(/^\d+$/)),
+                        chainId: Integer,
+                      }),
+                    ),
+                  }),
+                ),
+              }),
+            ),
             outTxs: z.optional(z.array(RequestTransaction)),
           }),
         ),
@@ -246,44 +264,130 @@ namespace schema {
 /** Validates a Relay request-list response and reports payload drift with field-level details. */
 export function parseDepositAddressRequests(value: unknown) {
   const parsed = schema.Requests.safeParse(value)
-  if (!parsed.success) throw new FundingProvider.ProviderPayloadError(z.prettifyError(parsed.error))
+  if (!parsed.success) throw new RoutesProvider.ProviderPayloadError(z.prettifyError(parsed.error))
   return parsed.data
 }
 
-/** Creates a Relay funding provider backed by `/quote/v2`. */
-export function relay(options: relay.Options = {}): FundingProvider.Provider<'relay'> {
+/** Creates a Relay route provider backed by `/quote/v2`. */
+export function relay(options: relay.Options = {}): RoutesProvider.Provider<'relay'> {
   const userAddresses = parseUserAddresses(options.userAddresses)
   if (
     Object.entries(userAddresses).some(([chainId, address]) => invalidUserAddress(chainId, address))
   )
-    throw new FundingProvider.ProviderConfigurationError()
+    throw new RoutesProvider.ProviderConfigurationError()
 
   const endpoint = quoteEndpoint(options)
   const fetch = options.fetch ?? defaultFetch
   const now = options.now ?? (() => new Date())
+
+  async function listDepositAddressRequests(
+    parameters: RoutesProvider.listDepositAddressRequests.Parameters,
+    signal: AbortSignal,
+  ): Promise<RoutesProvider.listDepositAddressRequests.ReturnType> {
+    const requestUrl = requestsEndpoint(options)
+    if (parameters.requestId) requestUrl.searchParams.set('id', parameters.requestId)
+    else requestUrl.searchParams.set('depositAddress', parameters.address)
+    requestUrl.searchParams.set('includeChildRequests', 'true')
+    requestUrl.searchParams.set('limit', '50')
+    requestUrl.searchParams.set('sortBy', 'updatedAt')
+    requestUrl.searchParams.set('sortDirection', 'desc')
+    if (parameters.continuation)
+      requestUrl.searchParams.set('continuation', parameters.continuation)
+    const response = await RoutesProvider.requestJson(requestUrl, {
+      fetch,
+      headers: options.apiKey ? { 'x-api-key': options.apiKey } : undefined,
+      method: 'GET',
+      signal,
+    })
+    const parsed = parseDepositAddressRequests(response)
+    return {
+      ...(parsed.continuation ? { continuation: parsed.continuation } : {}),
+      requests: parsed.requests.map((request) => {
+        const outputTransactionHashes =
+          request.data?.outTxs?.flatMap((transaction) =>
+            transaction.txHash ? [transaction.txHash] : [],
+          ) ?? []
+        const subsidy = (() => {
+          const payment = request.data?.feeSponsorship?.actual?.sponsorPayment
+          if (!payment || BigInt(payment.amount) === 0n) return undefined
+          const chainId = `eip155:${payment.chainId}/`
+          const token = [parameters.destinationToken, parameters.sourceToken].find(
+            (token) =>
+              token?.tokenKey.startsWith(chainId) &&
+              token.address.toLowerCase() === payment.address.toLowerCase(),
+          )
+          if (!token) throw new RoutesProvider.ProviderPayloadError()
+          return {
+            amount: Value.tokenAmount({
+              baseUnits: payment.amount,
+              currency: token.currency,
+              decimals: token.decimals,
+            }),
+            provider: 'relay',
+            token,
+          }
+        })()
+        const refunded = (relayRefundStatuses as readonly string[]).includes(request.status)
+        const correlation = (() => {
+          const { protocol } = request
+          if (!protocol) return undefined
+          const relay = {
+            ...(protocol.deposit?.origin?.depositor
+              ? { depositor: protocol.deposit.origin.depositor }
+              : {}),
+            ...(protocol.deposit?.origin?.depository
+              ? { depository: protocol.deposit.origin.depository }
+              : {}),
+            ...(protocol.orderId ? { orderId: protocol.orderId } : {}),
+            ...(protocol.solver?.address ? { solver: protocol.solver.address } : {}),
+          }
+          if (Object.keys(relay).length === 0) return undefined
+          return schema.RequestCorrelation.parse({ relay })
+        })()
+        return {
+          createdAt: new Date(request.createdAt).toISOString(),
+          destinationTransactionHashes: refunded ? [] : outputTransactionHashes,
+          id: request.id,
+          ...(correlation ? { providerState: correlation } : {}),
+          ...(refunded && request.refundCurrencyData
+            ? { refundAmountExpected: request.refundCurrencyData.amount }
+            : {}),
+          refundTransactionHashes: refunded ? outputTransactionHashes : [],
+          sourceTransactionHashes: request.depositAddress?.depositTxHash
+            ? [request.depositAddress.depositTxHash]
+            : [],
+          ...(subsidy ? { subsidy } : {}),
+          status: request.status,
+          updatedAt: new Date(request.updatedAt).toISOString(),
+        }
+      }),
+    }
+  }
+
   const observeDepositAddressRequest = options.observation
     ? createDepositAddressObserver({
         ...options.observation,
         ...(options.apiKey ? { apiKey: options.apiKey } : {}),
         ...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
         fetch,
+        listDepositAddressRequests,
         now,
       })
     : undefined
   const webhook = (() => {
     if (!options.apiKey || !options.webhook) return undefined
     const { apiKey, webhook } = options
-    const verify = (input: FundingProvider.Webhook.verify.Parameters) =>
+    const verify = (input: RoutesProvider.Webhook.verify.Parameters) =>
       verifyWebhook(webhookOptions(input, apiKey))
     return {
-      async receive(input: FundingProvider.Webhook.receive.Parameters) {
+      async receive(input: RoutesProvider.Webhook.receive.Parameters) {
         const receivedAt = now().toISOString()
         const hint = (() => {
           try {
             return verify(input)
           } catch (cause) {
             webhook.onResult?.(
-              cause instanceof FundingProvider.WebhookAuthenticationError
+              cause instanceof RoutesProvider.WebhookAuthenticationError
                 ? 'authentication_failed'
                 : 'payload_invalid',
             )
@@ -295,7 +399,7 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
           return { type: 'ignored' as const }
         }
         const database = Db.get(webhook.db)
-        const address = await FundingDepositAddresses.getByProviderAddress(database, {
+        const address = await RoutesDepositAddresses.getByProviderAddress(database, {
           address: hint.address,
           providerId: 'relay',
         })
@@ -304,7 +408,7 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
           return { type: 'unknown_address' as const }
         }
         if (hint.requestId)
-          await FundingDepositRequestObservations.observeWebhook(database, {
+          await RoutesDepositRequestObservations.observeWebhook(database, {
             depositAddressId: address.id,
             providerRequestId: hint.requestId,
             receivedAt,
@@ -328,7 +432,7 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
             addressId: address.id,
             ...(hint.requestId ? { requestId: hint.requestId } : {}),
             trigger: 'webhook',
-            type: 'funding:deposit-address:reconcile',
+            type: 'routes:deposit-address:reconcile',
             ...(webhookTiming ? { webhookTiming } : {}),
           })
         } catch (cause) {
@@ -342,7 +446,7 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
     }
   })()
 
-  return FundingProvider.from({
+  return RoutesProvider.from({
     id: 'relay',
     name: 'Relay',
     ...(webhook ? { webhook } : {}),
@@ -356,10 +460,10 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
             sourceToken: candidate.sourceToken,
           }))
       )
-        throw new FundingProvider.ProviderUnavailableError()
+        throw new RoutesProvider.ProviderUnavailableError()
       const quote = await (async () => {
         try {
-          return await FundingProvider.requestJson(endpoint, {
+          return await RoutesProvider.requestJson(endpoint, {
             body: {
               amount,
               destinationChainId: relayChainId(candidate.route.destination.chain),
@@ -379,19 +483,19 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
             signal,
           })
         } catch (cause) {
-          if (FundingProvider.unavailable(cause, ['NO_QUOTES', 'NO_ROUTE', 'UNSUPPORTED_ROUTE']))
-            throw new FundingProvider.ProviderUnavailableError()
+          if (RoutesProvider.unavailable(cause, ['NO_QUOTES', 'NO_ROUTE', 'UNSUPPORTED_ROUTE']))
+            throw new RoutesProvider.ProviderUnavailableError()
           throw cause
         }
       })()
       const parsed = schema.DepositAddress.safeParse(quote)
-      if (!parsed.success) throw new FundingProvider.ProviderPayloadError()
+      if (!parsed.success) throw new RoutesProvider.ProviderPayloadError()
       if (parsed.data.details.currencyIn.amount !== amount)
-        throw new FundingProvider.ProviderPayloadError()
+        throw new RoutesProvider.ProviderPayloadError()
       const step = parsed.data.steps.find(
         (candidate) => candidate.depositAddress && candidate.requestId,
       )
-      if (!step?.depositAddress || !step.requestId) throw new FundingProvider.ProviderPayloadError()
+      if (!step?.depositAddress || !step.requestId) throw new RoutesProvider.ProviderPayloadError()
       const checkEndpoint = step.items?.find((item) => item.check)?.check?.endpoint
       const providerFee = parsed.data.fees?.relayer?.amount
       return {
@@ -410,7 +514,7 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
     async getQuote({ candidate, route }, signal) {
       const userAddress = userAddresses[route.source.chain.id]
       if (userAddress === undefined)
-        return FundingProvider.unavailableResult({
+        return RoutesProvider.unavailableResult({
           detail: 'relay:quote-v2',
           message: 'QUOTE_USER_NOT_CONFIGURED',
           now: now(),
@@ -418,7 +522,7 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
         })
       const recipientAddress = userAddresses[route.destination.chain.id]
       if (recipientAddress === undefined)
-        return FundingProvider.unavailableResult({
+        return RoutesProvider.unavailableResult({
           detail: 'relay:quote-v2',
           message: 'QUOTE_RECIPIENT_NOT_CONFIGURED',
           now: now(),
@@ -427,7 +531,7 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
       const destinationChainId = relayChainId(route.destination.chain)
       const sourceChainId = relayChainId(route.source.chain)
       try {
-        const quote = await FundingProvider.requestJson(endpoint, {
+        const quote = await RoutesProvider.requestJson(endpoint, {
           body: {
             amount: candidate.sourceAmount.amount,
             destinationChainId,
@@ -444,7 +548,7 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
           signal,
         })
         const parsed = schema.Quote.safeParse(quote)
-        if (!parsed.success) throw new FundingProvider.ProviderPayloadError()
+        if (!parsed.success) throw new RoutesProvider.ProviderPayloadError()
         const destinationAmount = parsed.data.details?.currencyOut?.amount
         const status = destinationAmount
           ? { status: 'available' as const, tier: 'liquid' as const }
@@ -463,13 +567,13 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
           status: status.status,
         }
       } catch (cause) {
-        const unavailable = FundingProvider.unavailable(cause, [
+        const unavailable = RoutesProvider.unavailable(cause, [
           'NO_QUOTES',
           'NO_ROUTE',
           'UNSUPPORTED_ROUTE',
         ])
         if (!unavailable) throw cause
-        return FundingProvider.unavailableResult({
+        return RoutesProvider.unavailableResult({
           detail: 'relay:quote-v2',
           message: unavailable,
           now: now(),
@@ -477,75 +581,21 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
         })
       }
     },
-    async listDepositAddressRequests({ address, continuation, requestId }, signal) {
-      const requestUrl = requestsEndpoint(options)
-      if (requestId) requestUrl.searchParams.set('id', requestId)
-      else requestUrl.searchParams.set('depositAddress', address)
-      requestUrl.searchParams.set('includeChildRequests', 'true')
-      requestUrl.searchParams.set('limit', '50')
-      requestUrl.searchParams.set('sortBy', 'updatedAt')
-      requestUrl.searchParams.set('sortDirection', 'desc')
-      if (continuation) requestUrl.searchParams.set('continuation', continuation)
-      const response = await FundingProvider.requestJson(requestUrl, {
-        fetch,
-        headers: options.apiKey ? { 'x-api-key': options.apiKey } : undefined,
-        method: 'GET',
-        signal,
-      })
-      const parsed = parseDepositAddressRequests(response)
-      return {
-        ...(parsed.continuation ? { continuation: parsed.continuation } : {}),
-        requests: parsed.requests.map((request) => {
-          const outputTransactionHashes = request.data?.outTxs?.map((tx) => tx.txHash) ?? []
-          const refunded = (relayRefundStatuses as readonly string[]).includes(request.status)
-          const correlation = (() => {
-            const { protocol } = request
-            if (!protocol) return undefined
-            const relay = {
-              ...(protocol.deposit?.origin?.depositor
-                ? { depositor: protocol.deposit.origin.depositor }
-                : {}),
-              ...(protocol.deposit?.origin?.depository
-                ? { depository: protocol.deposit.origin.depository }
-                : {}),
-              ...(protocol.orderId ? { orderId: protocol.orderId } : {}),
-              ...(protocol.solver?.address ? { solver: protocol.solver.address } : {}),
-            }
-            if (Object.keys(relay).length === 0) return undefined
-            return schema.RequestCorrelation.parse({ relay })
-          })()
-          return {
-            createdAt: new Date(request.createdAt).toISOString(),
-            destinationTransactionHashes: refunded ? [] : outputTransactionHashes,
-            id: request.id,
-            ...(correlation ? { providerState: correlation } : {}),
-            ...(refunded && request.refundCurrencyData
-              ? { refundAmountExpected: request.refundCurrencyData.amount }
-              : {}),
-            refundTransactionHashes: refunded ? outputTransactionHashes : [],
-            sourceTransactionHashes: request.depositAddress?.depositTxHash
-              ? [request.depositAddress.depositTxHash]
-              : [],
-            status: request.status,
-            updatedAt: new Date(request.updatedAt).toISOString(),
-          }
-        }),
-      }
-    },
+    listDepositAddressRequests,
     ...(observeDepositAddressRequest ? { observeDepositAddressRequest } : {}),
     async prepareTransfer({ candidate, method, mode, recipient, sender, slippageBps }, signal) {
       // Catalog capabilities gate deposit addresses and exact destination
       // off this adapter; refuse them defensively if one slips through.
       if (method !== 'transaction' || mode !== 'exactSource')
-        throw new FundingProvider.ProviderConfigurationError()
+        throw new RoutesProvider.ProviderConfigurationError()
       const quote = await (async () => {
         try {
-          return await FundingProvider.requestJson(endpoint, {
+          return await RoutesProvider.requestJson(endpoint, {
             body: {
               amount: candidate.sourceAmount.amount,
-              destinationChainId: Number(FundingChain.eip155Id(candidate.route.destination.chain)),
+              destinationChainId: Number(RoutesChain.eip155Id(candidate.route.destination.chain)),
               destinationCurrency: candidate.destinationToken.address,
-              originChainId: Number(FundingChain.eip155Id(candidate.route.source.chain)),
+              originChainId: Number(RoutesChain.eip155Id(candidate.route.source.chain)),
               originCurrency: candidate.sourceToken.address,
               recipient,
               ...(slippageBps !== undefined ? { slippageTolerance: String(slippageBps) } : {}),
@@ -558,31 +608,31 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
             signal,
           })
         } catch (cause) {
-          if (FundingProvider.unavailable(cause, ['NO_QUOTES', 'NO_ROUTE', 'UNSUPPORTED_ROUTE']))
-            throw new FundingProvider.ProviderUnavailableError()
+          if (RoutesProvider.unavailable(cause, ['NO_QUOTES', 'NO_ROUTE', 'UNSUPPORTED_ROUTE']))
+            throw new RoutesProvider.ProviderUnavailableError()
           throw cause
         }
       })()
       const parsed = schema.PreparedQuote.safeParse(quote)
-      if (!parsed.success) throw new FundingProvider.ProviderPayloadError()
+      if (!parsed.success) throw new RoutesProvider.ProviderPayloadError()
       const { details, fees, steps } = parsed.data
       // The quoted input must match the request exactly; a drifted amount
       // would desynchronize the stored terms from the prepared calls.
       if (details.currencyIn.amount !== candidate.sourceAmount.amount)
-        throw new FundingProvider.ProviderPayloadError()
+        throw new RoutesProvider.ProviderPayloadError()
 
       const items = steps
         .filter((step) => step.kind === 'transaction')
         .flatMap((step) => step.items ?? [])
       const requestId = steps.find((step) => step.requestId)?.requestId
-      if (items.length === 0 || !requestId) throw new FundingProvider.ProviderPayloadError()
-      const sourceChainId = Number(FundingChain.eip155Id(candidate.route.source.chain))
+      if (items.length === 0 || !requestId) throw new RoutesProvider.ProviderPayloadError()
+      const sourceChainId = Number(RoutesChain.eip155Id(candidate.route.source.chain))
       for (const item of items)
         if (
           item.data.chainId !== sourceChainId ||
           item.data.from.toLowerCase() !== sender.toLowerCase()
         )
-          throw new FundingProvider.ProviderPayloadError()
+          throw new RoutesProvider.ProviderPayloadError()
 
       const checkEndpoint = items.find((item) => item.check)?.check?.endpoint
       // Relay's `relayer` fee is the solver's total source-side charge (gas
@@ -622,7 +672,7 @@ export declare namespace relay {
     /** Override for tests or Relay test environments. */
     baseUrl?: string | undefined
     /** Fetch implementation override for tests. */
-    fetch?: FundingProvider.Fetch | undefined
+    fetch?: RoutesProvider.Fetch | undefined
     /** Clock override for deterministic tests. */
     now?: (() => Date) | undefined
     /** EVM chain evidence used to accelerate authenticated provider delivery. */
@@ -630,14 +680,14 @@ export declare namespace relay {
     /** Deposit subsidy policy enabled for this integration. */
     subsidies?: Subsidy.Policy | undefined
     /** Optional source and destination quote wallets keyed by CAIP-2 chain id. */
-    userAddresses?: Readonly<Partial<Record<FundingChain.Id, string>>> | string | undefined
+    userAddresses?: Readonly<Partial<Record<RoutesChain.Id, string>>> | string | undefined
     /** Tempo infrastructure used to receive authenticated Relay webhooks. */
     webhook?: Webhook | undefined
   }
 
   /** Chain evidence configuration for Relay delivery observation. */
   type Observation = {
-    /** Authoritative funding database or per-request database factory. */
+    /** Authoritative routes database or per-request database factory. */
     db: Db.Source
     /** Tempo chain that receives a shared RPC URL override. */
     defaultChainId?: Viem.ChainId | undefined
@@ -647,10 +697,10 @@ export declare namespace relay {
 
   /** Authenticated Relay webhook integration attached to a provider instance. */
   type Webhook = {
-    /** Authoritative funding database or per-request database factory. */
+    /** Authoritative routes database or per-request database factory. */
     db: Db.Source
     /** Enqueues one bounded reconciliation hint. */
-    dispatch: (message: FundingProvider.Webhook.receive.Dispatchable) => Promise<void>
+    dispatch: (message: RoutesProvider.Webhook.receive.Dispatchable) => Promise<void>
     /** Observes one bounded webhook disposition. */
     onResult?: ((result: WebhookResult) => void) | undefined
   }
@@ -674,13 +724,13 @@ function parseUserAddresses(value: relay.Options['userAddresses']) {
           try {
             return JSON.parse(value) as unknown
           } catch {
-            throw new FundingProvider.ProviderConfigurationError()
+            throw new RoutesProvider.ProviderConfigurationError()
           }
         })()
       : value
   if (!addresses || typeof addresses !== 'object' || Array.isArray(addresses))
-    throw new FundingProvider.ProviderConfigurationError()
-  return addresses as Readonly<Partial<Record<FundingChain.Id, string>>>
+    throw new RoutesProvider.ProviderConfigurationError()
+  return addresses as Readonly<Partial<Record<RoutesChain.Id, string>>>
 }
 
 function invalidUserAddress(chainId: string, address: unknown) {
@@ -708,7 +758,8 @@ function invalidUserAddress(chainId: string, address: unknown) {
 type DepositAddressObserverOptions = relay.Observation & {
   apiKey?: string | undefined
   baseUrl?: string | undefined
-  fetch: FundingProvider.Fetch
+  fetch: RoutesProvider.Fetch
+  listDepositAddressRequests: NonNullable<RoutesProvider.Provider['listDepositAddressRequests']>
   now: () => Date
 }
 
@@ -717,7 +768,7 @@ type RelayDeliveryObservation = z.output<typeof schema.DeliveryObservation>['rel
 
 function createDepositAddressObserver(
   options: DepositAddressObserverOptions,
-): NonNullable<FundingProvider.Provider['observeDepositAddressRequest']> {
+): NonNullable<RoutesProvider.Provider['observeDepositAddressRequest']> {
   let chainsExpiresAt = 0
   let chainsPromise: Promise<readonly RelayChain[]> | undefined
   let urlsExpiresAt = 0
@@ -725,7 +776,7 @@ function createDepositAddressObserver(
   const getChains = (signal: AbortSignal) => {
     if (chainsPromise && options.now().getTime() < chainsExpiresAt) return chainsPromise
     chainsExpiresAt = options.now().getTime() + relayChainsCacheTtlMs
-    chainsPromise = FundingProvider.requestJson(chainsEndpoint(options), {
+    chainsPromise = RoutesProvider.requestJson(chainsEndpoint(options), {
       fetch: options.fetch,
       headers: options.apiKey ? { 'x-api-key': options.apiKey } : undefined,
       signal,
@@ -741,7 +792,7 @@ function createDepositAddressObserver(
   const getUrls = () => {
     if (urlsPromise && options.now().getTime() < urlsExpiresAt) return urlsPromise
     urlsExpiresAt = options.now().getTime() + relayChainsCacheTtlMs
-    urlsPromise = FundingCatalog.read(Db.get(options.db))
+    urlsPromise = RoutesCatalog.read(Db.get(options.db))
       .then(
         (catalog) =>
           new Map<string, readonly string[]>(
@@ -793,8 +844,10 @@ function createDepositAddressObserver(
     const solvers = destinationChain?.solverAddresses
     if (
       !depository ||
+      !Address.validate(depository, { strict: false }) ||
       !solvers ||
       solvers.length === 0 ||
+      solvers.some((solver) => !Address.validate(solver, { strict: false })) ||
       !sourceUrls?.length ||
       !destinationUrls?.length
     )
@@ -867,6 +920,60 @@ function createDepositAddressObserver(
     })()
     if (!sourceObservation) return { type: 'pending' }
 
+    const indexedRequest = await (async () => {
+      let continuation: string | undefined
+      try {
+        for (let page = 0; page < relayRequestPageLimit; page++) {
+          const result = parameters.request
+            ? { continuation: undefined, requests: [parameters.request] }
+            : await options.listDepositAddressRequests(
+                {
+                  address: parameters.address,
+                  ...(continuation ? { continuation } : {}),
+                  destinationToken: parameters.destinationToken,
+                  sourceToken: parameters.sourceToken,
+                },
+                signal,
+              )
+          const request = result.requests.find((request) => {
+            if (!(deliveryObservationStatuses as readonly string[]).includes(request.status))
+              return false
+            const parsed = schema.RequestCorrelation.safeParse(request.providerState)
+            return Boolean(
+              parsed.success &&
+              parsed.data.relay.orderId &&
+              Hex.isEqual(
+                parsed.data.relay.orderId as Hex.Hex,
+                sourceObservation.orderId as Hex.Hex,
+              ),
+            )
+          })
+          if (request || !result.continuation) return request
+          continuation = result.continuation
+        }
+      } catch (cause) {
+        if (signal.aborted) throw cause
+        // Relay indexing is optional evidence, so preserve the onchain fallback when it is unavailable.
+      }
+      return undefined
+    })()
+    if (indexedRequest && indexedRequest.destinationTransactionHashes.length > 0)
+      return {
+        destinationTransactionHashes: indexedRequest.destinationTransactionHashes,
+        providerState: {
+          relay: {
+            ...sourceObservation,
+            destinationObservedAt: options.now().toISOString(),
+          },
+        },
+        providerTransactionHashes: [
+          sourceObservation.sourceSweepTransactionHash,
+          ...indexedRequest.destinationTransactionHashes,
+        ],
+        ...(indexedRequest.subsidy ? { subsidy: indexedRequest.subsidy } : {}),
+        type: 'verified',
+      }
+
     const destinationClient = Viem.createEvmClient({ fetch: options.fetch, urls: destinationUrls })
     const destinationHead = await getBlockNumber(destinationClient, { cacheTime: 0 })
     const destinationLogs = await getLogs(destinationClient, {
@@ -1006,7 +1113,7 @@ function minimum(left: bigint, right: bigint): bigint {
 
 function relayEvmChain(
   chains: readonly RelayChain[],
-  chain: FundingProvider.ChainRef,
+  chain: RoutesProvider.ChainRef,
 ): RelayChain | undefined {
   if (chain.kind !== 'evm') return undefined
   const match = /^eip155:(\d+)$/.exec(chain.id)
@@ -1021,7 +1128,7 @@ type VerifyWebhookOptions = {
   timestamp: string
 }
 
-function verifyWebhook(options: VerifyWebhookOptions): FundingProvider.Webhook.verify.ReturnType {
+function verifyWebhook(options: VerifyWebhookOptions): RoutesProvider.Webhook.verify.ReturnType {
   const timestamp = Number(options.timestamp)
   if (!Number.isSafeInteger(timestamp)) throw new WebhookSignatureError()
   if (Math.abs(Date.now() - timestamp) > webhookSignatureToleranceMs)
@@ -1052,7 +1159,7 @@ function verifyWebhook(options: VerifyWebhookOptions): FundingProvider.Webhook.v
 }
 
 function webhookOptions(
-  input: FundingProvider.Webhook.verify.Parameters,
+  input: RoutesProvider.Webhook.verify.Parameters,
   secret: string,
 ): VerifyWebhookOptions {
   const signature = input.headers.get('x-signature-sha256')
@@ -1093,20 +1200,20 @@ function webhookTimestamp(value: number): string {
   }
 }
 
-function relayChainId(chain: FundingProvider.Chain): number {
-  if (chain.id.startsWith('eip155:')) return Number(FundingChain.eip155Id(chain))
+function relayChainId(chain: RoutesProvider.Chain): number {
+  if (chain.id.startsWith('eip155:')) return Number(RoutesChain.eip155Id(chain))
   // Relay uses a numeric chain ID for Solana instead of its CAIP-2 reference.
   if (chain.id === 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp') return 792_703_809
   if (chain.id.startsWith('tron:')) return Number(chain.id.slice('tron:'.length))
-  throw new FundingProvider.ProviderConfigurationError()
+  throw new RoutesProvider.ProviderConfigurationError()
 }
 
 /** Relay webhook signature is missing, stale, or invalid. */
-export class WebhookSignatureError extends FundingProvider.WebhookAuthenticationError {
-  override name = 'Funding.Provider.Relay.WebhookSignatureError'
+export class WebhookSignatureError extends RoutesProvider.WebhookAuthenticationError {
+  override name = 'Routes.Provider.Relay.WebhookSignatureError'
 }
 
 /** Relay webhook body does not match the expected status event shape. */
-export class WebhookPayloadError extends FundingProvider.WebhookPayloadError {
-  override name = 'Funding.Provider.Relay.WebhookPayloadError'
+export class WebhookPayloadError extends RoutesProvider.WebhookPayloadError {
+  override name = 'Routes.Provider.Relay.WebhookPayloadError'
 }