tapimo 0.15.1 → 0.18.0

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

@@ -1,24 +1,51 @@
-import { AbiEvent, AbiFunction, Address, Base58, Bytes, Hash, Hex } from 'ox'
+import { AbiEvent, AbiFunction, Address, Base58, Bytes, Hash, Hex, Value as core_Value } from 'ox'
 import { getBlockNumber, getLogs, getTransaction, getTransactionReceipt } from 'viem/actions'
 import * as z from 'zod/mini'
 
 import * as Db from '../../../db/Db.js'
 import * as RoutesDepositAddresses from '../../../db/tables/routesDepositAddresses.js'
 import * as RoutesDepositRequestObservations from '../../../db/tables/routesDepositRequestObservations.js'
+import * as Store from '../../Store.js'
 import * as Value from '../../Value.js'
 import * as Viem from '../../Viem.js'
 import * as RoutesCatalog from '../Catalog.js'
 import * as RoutesChain from '../Chain.js'
 import * as Evidence from '../Evidence.js'
 import * as RoutesProvider from '../Provider.js'
+import * as ProviderQuota from '../Quota.js'
 import * as Subsidy from '../Subsidy.js'
 
 const defaultBaseUrl = 'https://api.relay.link'
 const defaultFetch: RoutesProvider.Fetch = (input, init) => globalThis.fetch(input, init)
 const deliveryBackfillBlocks = 256n
+// Quote-time fee insufficiency is an expected rejection, not a provider outage.
+const quoteUnavailableCodes = ['AMOUNT_TOO_LOW', 'NO_QUOTES', 'NO_ROUTE', 'UNSUPPORTED_ROUTE']
+// Recheck the Relay key dashboard before changing account-specific quotas.
+// Treat /quote/v2 as generic /quote until Relay confirms its bridge classification.
+const quoteRateLimit = 10
+// Reserve two requests for operations that must turn an accepted quote into work.
+const quoteReadRateLimit = 8
+const quoteRateLimitWindowMs = 1_000
+const quoteQuotaStoreKey = 'routes:relay:quote-v2'
 const relayChainsCacheTtlMs = 60_000
 const relayRefundStatuses = ['refund', 'refunded'] as const
 const relayRequestPageLimit = 100
+const requestsRateLimit = 20
+const requestsRateLimitWindowMs = 1_000
+const requestsQuotaStoreKey = 'routes:relay:requests-v3'
+const chainsTimeoutMs = 10_000
+const requestsTimeoutMs = 10_000
+// Relay app-balance sponsorship can settle in Base USDC even when neither route leg uses it.
+const sponsorToken = {
+  address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+  currency: 'USD',
+  decimals: 6,
+  name: 'USD Coin',
+  standard: 'ERC-20',
+  symbol: 'USDC',
+  tokenKey: 'eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+  verified: true,
+} satisfies RoutesProvider.TokenRef
 const sourceSweepForwardBlocks = 256n
 const depositErc20FullAllowance = AbiFunction.from(
   'function depositErc20(address depositor,address token,bytes32 id)',
@@ -124,7 +151,9 @@ namespace schema {
   })
 
   export const DepositAddress = z.object({
-    details: PreparedQuote.shape.details,
+    details: z.extend(PreparedQuote.shape.details, {
+      isFixedRate: z.optional(z.boolean()),
+    }),
     fees: PreparedQuote.shape.fees,
     steps: z.array(
       z.object({
@@ -250,6 +279,64 @@ namespace schema {
     ),
   })
 
+  const TransferCurrency = z.object({
+    amount: Decimal,
+    currency: z.object({
+      address: z.string(),
+      chainId: Integer,
+    }),
+  })
+
+  const TransferTransaction = z.object({
+    chainId: Integer,
+    status: z.string(),
+    txHash: z.nullish(z.string()),
+  })
+
+  export const TransferRequests = z.object({
+    requests: z.array(
+      z.object({
+        data: z.optional(
+          z.object({
+            inTxs: z.optional(z.array(TransferTransaction)),
+            outTxs: z.optional(z.array(TransferTransaction)),
+            route: z.optional(
+              z.object({
+                actual: z.optional(
+                  z.object({
+                    destination: z.optional(z.object({ outputCurrency: TransferCurrency })),
+                    origin: z.optional(z.object({ inputCurrency: TransferCurrency })),
+                  }),
+                ),
+              }),
+            ),
+          }),
+        ),
+        id: z.string().check(z.minLength(1)),
+        protocol: z.nullish(
+          z.object({
+            deposit: z.optional(
+              z.object({
+                origin: z.optional(
+                  z.object({
+                    depository: z.optional(z.string()),
+                  }),
+                ),
+              }),
+            ),
+          }),
+        ),
+        recipient: z.optional(z.string()),
+        sender: z.optional(z.string()),
+        status: z.string().check(z.minLength(1)),
+      }),
+    ),
+  })
+
+  export const TransferCorrelation = z.object({
+    requestId: z.string().check(z.minLength(1)),
+  })
+
   export const WebhookPayload = z.object({
     data: z.object({
       depositAddress: z.nullable(z.object({ address: z.string().check(z.minLength(1)) })),
@@ -279,6 +366,84 @@ export function relay(options: relay.Options = {}): RoutesProvider.Provider<'rel
   const endpoint = quoteEndpoint(options)
   const fetch = options.fetch ?? defaultFetch
   const now = options.now ?? (() => new Date())
+  const rateLimitStore = options.rateLimitStore ?? Store.memory()
+  const verifyTransfers = options.observation
+    ? Evidence.createVerifier({
+        ...options.observation,
+        fetch,
+      })
+    : undefined
+  let transferChainsExpiresAt = 0
+  let transferChainsPromise: Promise<readonly RelayChain[]> | undefined
+  const getTransferChains = (signal: AbortSignal) => {
+    if (transferChainsPromise && now().getTime() < transferChainsExpiresAt)
+      return transferChainsPromise
+    transferChainsExpiresAt = now().getTime() + relayChainsCacheTtlMs
+    transferChainsPromise = RoutesProvider.requestJson(chainsEndpoint(options), {
+      fetch,
+      headers: options.apiKey ? { 'x-api-key': options.apiKey } : undefined,
+      signal: AbortSignal.any([signal, AbortSignal.timeout(chainsTimeoutMs)]),
+    })
+      .then((value) => schema.Chains.parse(value).chains)
+      .catch((cause) => {
+        transferChainsExpiresAt = 0
+        transferChainsPromise = undefined
+        if (cause instanceof DOMException && cause.name === 'TimeoutError')
+          throw new RoutesProvider.ProviderTimeoutError()
+        throw cause
+      })
+    return transferChainsPromise
+  }
+
+  const consumeQuoteQuota = (limit: number) =>
+    ProviderQuota.consume(rateLimitStore, {
+      key: quoteQuotaStoreKey,
+      limit,
+      now: now(),
+      windowMs: quoteRateLimitWindowMs,
+    })
+  const consumeRequestsQuota = () =>
+    ProviderQuota.consume(rateLimitStore, {
+      key: requestsQuotaStoreKey,
+      limit: requestsRateLimit,
+      now: now(),
+      windowMs: requestsRateLimitWindowMs,
+    })
+  const blockQuoteOnRateLimit = (cause: unknown) =>
+    ProviderQuota.blockOnRateLimit(rateLimitStore, cause, {
+      key: quoteQuotaStoreKey,
+      now: now(),
+      windowMs: quoteRateLimitWindowMs,
+    })
+  const blockRequestsOnRateLimit = (cause: unknown) =>
+    ProviderQuota.blockOnRateLimit(rateLimitStore, cause, {
+      key: requestsQuotaStoreKey,
+      now: now(),
+      windowMs: requestsRateLimitWindowMs,
+    })
+
+  const getTransferRequest = async (requestId: string, signal: AbortSignal) => {
+    const url = requestsEndpoint(options)
+    url.searchParams.set('id', requestId)
+    await consumeRequestsQuota()
+    const response = await RoutesProvider.requestJson(url, {
+      fetch,
+      headers: { 'x-api-key': options.apiKey! },
+      method: 'GET',
+      signal: AbortSignal.any([signal, AbortSignal.timeout(requestsTimeoutMs)]),
+    }).catch(async (cause) => {
+      await blockRequestsOnRateLimit(cause)
+      if (cause instanceof DOMException && cause.name === 'TimeoutError')
+        throw new RoutesProvider.ProviderTimeoutError()
+      throw cause
+    })
+    const requests = schema.TransferRequests.safeParse(response)
+    if (!requests.success) throw new RoutesProvider.ProviderPayloadError()
+    if (requests.data.requests.some((request) => request.id !== requestId))
+      throw new RoutesProvider.ProviderPayloadError()
+    if (requests.data.requests.length > 1) throw new RoutesProvider.ProviderPayloadError()
+    return requests.data.requests[0]
+  }
 
   async function listDepositAddressRequests(
     parameters: RoutesProvider.listDepositAddressRequests.Parameters,
@@ -293,12 +458,22 @@ export function relay(options: relay.Options = {}): RoutesProvider.Provider<'rel
     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,
-    })
+    await consumeRequestsQuota()
+    const response = await (async () => {
+      try {
+        return await RoutesProvider.requestJson(requestUrl, {
+          fetch,
+          headers: options.apiKey ? { 'x-api-key': options.apiKey } : undefined,
+          method: 'GET',
+          signal: AbortSignal.any([signal, AbortSignal.timeout(requestsTimeoutMs)]),
+        })
+      } catch (cause) {
+        await blockRequestsOnRateLimit(cause)
+        if (cause instanceof DOMException && cause.name === 'TimeoutError')
+          throw new RoutesProvider.ProviderTimeoutError()
+        throw cause
+      }
+    })()
     const parsed = parseDepositAddressRequests(response)
     return {
       ...(parsed.continuation ? { continuation: parsed.continuation } : {}),
@@ -311,7 +486,7 @@ export function relay(options: relay.Options = {}): RoutesProvider.Provider<'rel
           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(
+          const token = [parameters.destinationToken, parameters.sourceToken, sponsorToken].find(
             (token) =>
               token?.tokenKey.startsWith(chainId) &&
               token.address.toLowerCase() === payment.address.toLowerCase(),
@@ -450,9 +625,23 @@ export function relay(options: relay.Options = {}): RoutesProvider.Provider<'rel
     id: 'relay',
     name: 'Relay',
     ...(webhook ? { webhook } : {}),
-    async createDepositAddress({ amount, candidate, recipient, refundAddress, subsidize }, signal) {
+    async createDepositAddress(
+      { amount, candidate, recipient, refundAddress, subsidize, subsidyMaxAmount },
+      signal,
+    ) {
+      if (
+        subsidize &&
+        subsidyMaxAmount !== undefined &&
+        (candidate.sourceToken.currency !== 'USD' ||
+          !Subsidy.supportsGap(
+            { maxAmount: subsidyMaxAmount },
+            { amount: 0n, destinationToken: candidate.destinationToken },
+          ))
+      )
+        throw new RoutesProvider.ProviderUnavailableError()
       if (
         subsidize &&
+        subsidyMaxAmount === undefined &&
         (!options.subsidies ||
           !Subsidy.supports(options.subsidies, {
             amount,
@@ -463,11 +652,17 @@ export function relay(options: relay.Options = {}): RoutesProvider.Provider<'rel
         throw new RoutesProvider.ProviderUnavailableError()
       const quote = await (async () => {
         try {
+          await consumeQuoteQuota(quoteRateLimit)
+          const maximum = subsidyMaxAmount ?? options.subsidies?.maxAmount
           return await RoutesProvider.requestJson(endpoint, {
             body: {
               amount,
               destinationChainId: relayChainId(candidate.route.destination.chain),
               destinationCurrency: candidate.destinationToken.address,
+              ...(subsidize ? { fixedRate: '1:1' } : {}),
+              ...(subsidize && maximum !== undefined
+                ? { maxSubsidizationAmount: core_Value.from(maximum, 6).toString() }
+                : {}),
               originChainId: relayChainId(candidate.route.source.chain),
               originCurrency: candidate.sourceToken.address,
               recipient,
@@ -483,8 +678,11 @@ export function relay(options: relay.Options = {}): RoutesProvider.Provider<'rel
             signal,
           })
         } catch (cause) {
-          if (RoutesProvider.unavailable(cause, ['NO_QUOTES', 'NO_ROUTE', 'UNSUPPORTED_ROUTE']))
-            throw new RoutesProvider.ProviderUnavailableError()
+          await blockQuoteOnRateLimit(cause)
+          const unavailable = RoutesProvider.unavailable(cause, quoteUnavailableCodes)
+          if (unavailable === 'AMOUNT_TOO_LOW')
+            throw new RoutesProvider.AmountTooLowError(unavailable, { cause })
+          if (unavailable) throw new RoutesProvider.ProviderUnavailableError(unavailable, { cause })
           throw cause
         }
       })()
@@ -492,6 +690,21 @@ export function relay(options: relay.Options = {}): RoutesProvider.Provider<'rel
       if (!parsed.success) throw new RoutesProvider.ProviderPayloadError()
       if (parsed.data.details.currencyIn.amount !== amount)
         throw new RoutesProvider.ProviderPayloadError()
+      if (subsidize) {
+        const expected =
+          (BigInt(amount) * 10n ** BigInt(candidate.destinationToken.decimals)) /
+          10n ** BigInt(candidate.sourceToken.decimals)
+        // Relay can quote 1:1 with isFixedRate=false and a slippage-adjusted minimum; validate the quoted output.
+        if (BigInt(parsed.data.details.currencyOut.amount) !== expected)
+          // Relay may have issued an address already; retain the irrevocable claim on invalid terms.
+          throw new RoutesProvider.ProviderPayloadError(
+            `FIXED_RATE_MISMATCH: ${JSON.stringify({
+              amount: parsed.data.details.currencyOut.amount,
+              expected: expected.toString(),
+              isFixedRate: parsed.data.details.isFixedRate ?? null,
+            })}`,
+          )
+      }
       const step = parsed.data.steps.find(
         (candidate) => candidate.depositAddress && candidate.requestId,
       )
@@ -502,6 +715,7 @@ export function relay(options: relay.Options = {}): RoutesProvider.Provider<'rel
         address: step.depositAddress,
         correlation: {
           ...(checkEndpoint ? { checkEndpoint } : {}),
+          ...(subsidize ? { fixedRate: '1:1' as const } : {}),
           requestId: step.requestId,
         },
         destinationAmount: parsed.data.details.currencyOut.amount,
@@ -531,6 +745,7 @@ export function relay(options: relay.Options = {}): RoutesProvider.Provider<'rel
       const destinationChainId = relayChainId(route.destination.chain)
       const sourceChainId = relayChainId(route.source.chain)
       try {
+        await consumeQuoteQuota(quoteReadRateLimit)
         const quote = await RoutesProvider.requestJson(endpoint, {
           body: {
             amount: candidate.sourceAmount.amount,
@@ -567,11 +782,8 @@ export function relay(options: relay.Options = {}): RoutesProvider.Provider<'rel
           status: status.status,
         }
       } catch (cause) {
-        const unavailable = RoutesProvider.unavailable(cause, [
-          'NO_QUOTES',
-          'NO_ROUTE',
-          'UNSUPPORTED_ROUTE',
-        ])
+        await blockQuoteOnRateLimit(cause)
+        const unavailable = RoutesProvider.unavailable(cause, quoteUnavailableCodes)
         if (!unavailable) throw cause
         return RoutesProvider.unavailableResult({
           detail: 'relay:quote-v2',
@@ -590,12 +802,13 @@ export function relay(options: relay.Options = {}): RoutesProvider.Provider<'rel
         throw new RoutesProvider.ProviderConfigurationError()
       const quote = await (async () => {
         try {
+          await consumeQuoteQuota(quoteRateLimit)
           return await RoutesProvider.requestJson(endpoint, {
             body: {
               amount: candidate.sourceAmount.amount,
-              destinationChainId: Number(RoutesChain.eip155Id(candidate.route.destination.chain)),
+              destinationChainId: relayChainId(candidate.route.destination.chain),
               destinationCurrency: candidate.destinationToken.address,
-              originChainId: Number(RoutesChain.eip155Id(candidate.route.source.chain)),
+              originChainId: relayChainId(candidate.route.source.chain),
               originCurrency: candidate.sourceToken.address,
               recipient,
               ...(slippageBps !== undefined ? { slippageTolerance: String(slippageBps) } : {}),
@@ -608,8 +821,9 @@ export function relay(options: relay.Options = {}): RoutesProvider.Provider<'rel
             signal,
           })
         } catch (cause) {
-          if (RoutesProvider.unavailable(cause, ['NO_QUOTES', 'NO_ROUTE', 'UNSUPPORTED_ROUTE']))
-            throw new RoutesProvider.ProviderUnavailableError()
+          await blockQuoteOnRateLimit(cause)
+          const unavailable = RoutesProvider.unavailable(cause, quoteUnavailableCodes)
+          if (unavailable) throw new RoutesProvider.ProviderUnavailableError(unavailable, { cause })
           throw cause
         }
       })()
@@ -626,7 +840,7 @@ export function relay(options: relay.Options = {}): RoutesProvider.Provider<'rel
         .flatMap((step) => step.items ?? [])
       const requestId = steps.find((step) => step.requestId)?.requestId
       if (items.length === 0 || !requestId) throw new RoutesProvider.ProviderPayloadError()
-      const sourceChainId = Number(RoutesChain.eip155Id(candidate.route.source.chain))
+      const sourceChainId = relayChainId(candidate.route.source.chain)
       for (const item of items)
         if (
           item.data.chainId !== sourceChainId ||
@@ -661,6 +875,138 @@ export function relay(options: relay.Options = {}): RoutesProvider.Provider<'rel
         sampledAt: now().toISOString(),
       }
     },
+    ...(verifyTransfers && options.apiKey
+      ? {
+          async verifySourceTransaction(
+            { destinationChain, providerState, sourceChain, transactionHash, transfer },
+            signal,
+          ) {
+            const correlation = schema.TransferCorrelation.safeParse(providerState)
+            if (
+              !correlation.success ||
+              sourceChain.kind !== 'evm' ||
+              (destinationChain.kind !== 'evm' && destinationChain.kind !== 'solana') ||
+              !transfer.sender ||
+              transfer.method !== 'transaction' ||
+              transfer.mode !== 'exactSource'
+            )
+              return { type: 'invalid' as const }
+            const request = await getTransferRequest(correlation.data.requestId, signal)
+            if (!request) return { type: 'pending' as const }
+            if (!transferRequestMatches(request, { destinationChain, sourceChain, transfer }))
+              return { type: 'invalid' as const }
+            const source = request.data?.inTxs?.find(
+              (entry) =>
+                entry.chainId === relayChainId(sourceChain) &&
+                entry.txHash?.toLowerCase() === transactionHash.toLowerCase(),
+            )
+            if (!source) return { type: 'pending' as const }
+            if (
+              source.status === 'failure' ||
+              source.status === 'failed' ||
+              source.status === 'cancelled' ||
+              source.status === 'canceled'
+            )
+              return { type: 'invalid' as const }
+            if (source.status !== 'success') return { type: 'pending' as const }
+            const chains = await getTransferChains(signal)
+            const depository = relayEvmChain(chains, sourceChain)?.protocol?.v2?.depository
+            if (!depository || !Address.validate(depository, { strict: false }))
+              throw new RoutesProvider.ProviderConfigurationError()
+            const reportedDepository = request.protocol?.deposit?.origin?.depository
+            if (
+              reportedDepository &&
+              (!Address.validate(reportedDepository, { strict: false }) ||
+                !Address.isEqual(
+                  reportedDepository as Address.Address,
+                  depository as Address.Address,
+                ))
+            )
+              return { type: 'invalid' as const }
+            const evidence = await verifyTransfers({
+              chain: sourceChain,
+              recipient: depository,
+              token: transfer.sourceToken,
+              transactionHash,
+            })
+            const amount = evidence
+              .filter((entry) => entry.sender?.toLowerCase() === transfer.sender!.toLowerCase())
+              .reduce((total, entry) => total + BigInt(entry.amount), 0n)
+            if (amount === 0n) return { type: 'pending' as const }
+            if (amount !== BigInt(transfer.sourceAmount.baseUnits))
+              return { type: 'invalid' as const }
+            return { type: 'verified' as const }
+          },
+          async verifyDestinationDelivery(
+            { destinationChain, providerState, sourceChain, transfer },
+            signal,
+          ) {
+            const correlation = schema.TransferCorrelation.safeParse(providerState)
+            if (
+              !correlation.success ||
+              sourceChain.kind !== 'evm' ||
+              (destinationChain.kind !== 'evm' && destinationChain.kind !== 'solana')
+            )
+              return { type: 'invalid' as const }
+            const request = await getTransferRequest(correlation.data.requestId, signal)
+            if (!request) return { type: 'pending' as const }
+            if (!transferRequestMatches(request, { destinationChain, sourceChain, transfer }))
+              return { type: 'invalid' as const }
+            if (
+              request.status === 'failure' ||
+              request.status === 'fallback' ||
+              request.status === 'refund' ||
+              request.status === 'refunded'
+            )
+              return {
+                statusReason: {
+                  code: 'manual_recovery_required' as const,
+                  message: 'Relay could not complete the destination transfer.',
+                },
+                type: 'action-required' as const,
+              }
+            if (request.status !== 'success') return { type: 'pending' as const }
+            const destination = request.data?.route?.actual?.destination?.outputCurrency
+            const outputs = request.data?.outTxs?.filter(
+              (entry) => entry.chainId === relayChainId(destinationChain),
+            )
+            if (
+              !destination ||
+              !outputs ||
+              outputs.length !== 1 ||
+              outputs[0]?.status !== 'success' ||
+              !outputs[0].txHash
+            )
+              return { type: 'pending' as const }
+            const transactionHash = outputs[0].txHash
+            const evidence = await verifyTransfers({
+              chain: destinationChain,
+              recipient: transfer.recipient,
+              token: transfer.destinationToken,
+              transactionHash,
+            })
+            const amount = evidence.reduce((total, entry) => total + BigInt(entry.amount), 0n)
+            if (amount === 0n) return { type: 'pending' as const }
+            if (amount !== BigInt(destination.amount)) return { type: 'invalid' as const }
+            if (
+              transfer.destinationAmountMin &&
+              amount < BigInt(transfer.destinationAmountMin.baseUnits)
+            )
+              return {
+                statusReason: {
+                  code: 'manual_recovery_required' as const,
+                  message: 'Relay delivered less than the quoted minimum destination amount.',
+                },
+                type: 'action-required' as const,
+              }
+            return {
+              destinationAmount: amount.toString(),
+              transactionHash,
+              type: 'verified' as const,
+            }
+          },
+        }
+      : {}),
   })
 }
 
@@ -677,6 +1023,8 @@ export declare namespace relay {
     now?: (() => Date) | undefined
     /** EVM chain evidence used to accelerate authenticated provider delivery. */
     observation?: Observation | undefined
+    /** Atomic store used to enforce the shared Relay `/quote/v2` quota. */
+    rateLimitStore?: Store.Store | undefined
     /** Deposit subsidy policy enabled for this integration. */
     subsidies?: Subsidy.Policy | undefined
     /** Optional source and destination quote wallets keyed by CAIP-2 chain id. */
@@ -988,13 +1336,8 @@ function createDepositAddressObserver(
       (address) => address as Address.Address,
     )
     const correlatedTransactionHashes: Hex.Hex[] = []
-    const uncorrelatedTransactionHashes: Hex.Hex[] = []
     for (const log of destinationLogs) {
-      if (
-        !log.transactionHash ||
-        correlatedTransactionHashes.includes(log.transactionHash) ||
-        uncorrelatedTransactionHashes.includes(log.transactionHash)
-      )
+      if (!log.transactionHash || correlatedTransactionHashes.includes(log.transactionHash))
         continue
       const event = decodeEvent(transferEvent, log)
       if (
@@ -1014,19 +1357,13 @@ function createDepositAddressObserver(
         !Address.isEqual(transaction.to, parameters.destinationToken.address as Address.Address) ||
         !Address.isEqual(call.recipient, event.to) ||
         call.amount !== event.value ||
-        (call.orderId && !Hex.isEqual(call.orderId, sourceObservation.orderId as Hex.Hex))
+        !call.orderId ||
+        !Hex.isEqual(call.orderId, sourceObservation.orderId as Hex.Hex)
       )
         continue
-      if (call.orderId) correlatedTransactionHashes.push(log.transactionHash)
-      else uncorrelatedTransactionHashes.push(log.transactionHash)
+      correlatedTransactionHashes.push(log.transactionHash)
     }
-    const destinationTransactionHashes = (() => {
-      if (correlatedTransactionHashes.length > 0) return correlatedTransactionHashes
-      // Provider-independent completion requires the Relay order id to bind both chain legs.
-      if (!parameters.request) return []
-      if (uncorrelatedTransactionHashes.length === 1) return uncorrelatedTransactionHashes
-      return []
-    })()
+    const destinationTransactionHashes = correlatedTransactionHashes
     const providerState = { relay: sourceObservation }
     if (destinationTransactionHashes.length === 0)
       return {
@@ -1208,6 +1545,54 @@ function relayChainId(chain: RoutesProvider.Chain): number {
   throw new RoutesProvider.ProviderConfigurationError()
 }
 
+function transferRequestMatches(
+  request: z.output<typeof schema.TransferRequests>['requests'][number],
+  options: Pick<
+    RoutesProvider.verifySourceTransaction.Parameters,
+    'destinationChain' | 'sourceChain' | 'transfer'
+  >,
+): boolean {
+  const { destinationChain, sourceChain, transfer } = options
+  const actual = request.data?.route?.actual
+  if (
+    !transfer.sender ||
+    !request.sender ||
+    !request.recipient ||
+    !Address.validate(request.sender, { strict: false }) ||
+    !Address.isEqual(request.sender as Address.Address, transfer.sender as Address.Address) ||
+    (destinationChain.kind === 'evm'
+      ? !Address.validate(request.recipient, { strict: false }) ||
+        !Address.isEqual(
+          request.recipient as Address.Address,
+          transfer.recipient as Address.Address,
+        )
+      : request.recipient !== transfer.recipient)
+  )
+    return false
+  if (!actual) return true
+  const source = actual.origin?.inputCurrency
+  const destination = actual.destination?.outputCurrency
+  return (
+    (!source ||
+      (source.currency.chainId === relayChainId(sourceChain) &&
+        Address.validate(source.currency.address, { strict: false }) &&
+        Address.isEqual(
+          source.currency.address as Address.Address,
+          transfer.sourceToken.address as Address.Address,
+        ) &&
+        source.amount === transfer.sourceAmount.baseUnits)) &&
+    (!destination ||
+      (destination.currency.chainId === relayChainId(destinationChain) &&
+        (destinationChain.kind === 'evm'
+          ? Address.validate(destination.currency.address, { strict: false }) &&
+            Address.isEqual(
+              destination.currency.address as Address.Address,
+              transfer.destinationToken.address as Address.Address,
+            )
+          : destination.currency.address === transfer.destinationToken.address)))
+  )
+}
+
 /** Relay webhook signature is missing, stale, or invalid. */
 export class WebhookSignatureError extends RoutesProvider.WebhookAuthenticationError {
   override name = 'Routes.Provider.Relay.WebhookSignatureError'

package/src/internal/routes/providers/rhino.ts

@@ -1,12 +1,16 @@
 import { Value as core_Value } from 'ox'
 import * as z from 'zod/mini'
 
+import * as Store from '../../Store.js'
 import type * as RoutesChain from '../Chain.js'
-import type * as RoutesToken from '../Token.js'
 import * as RoutesProvider from '../Provider.js'
+import * as ProviderQuota from '../Quota.js'
+import type * as RoutesToken from '../Token.js'
 
 const defaultBaseUrl = 'https://api.rhino.fi/bridge'
 const defaultFetch: RoutesProvider.Fetch = (input, init) => globalThis.fetch(input, init)
+const rateLimitWindowMs = 1_000
+const quotaStoreKey = 'routes:rhino:bridge-swap-public'
 
 const chainIds = {
   'eip155:4217': 'TEMPO',
@@ -38,6 +42,7 @@ export function rhino(options: rhino.Options = {}) {
   endpoint.pathname = `${endpoint.pathname.replace(/\/+$/, '')}/quote/bridge-swap/public`
   const fetch = options.fetch ?? defaultFetch
   const now = options.now ?? (() => new Date())
+  const rateLimitStore = options.rateLimitStore ?? Store.memory()
 
   return RoutesProvider.from({
     id: 'rhino',
@@ -58,6 +63,7 @@ export function rhino(options: rhino.Options = {}) {
       }).toString()
 
       try {
+        await ProviderQuota.check(rateLimitStore, { key: quotaStoreKey, now: now() })
         const quote = await RoutesProvider.requestJson(url, {
           fetch,
           headers: cache.bypass ? { 'cache-control': 'no-cache' } : undefined,
@@ -95,6 +101,11 @@ export function rhino(options: rhino.Options = {}) {
           status: 'available',
         }
       } catch (cause) {
+        await ProviderQuota.blockOnRateLimit(rateLimitStore, cause, {
+          key: quotaStoreKey,
+          now: now(),
+          windowMs: rateLimitWindowMs,
+        })
         const unavailable = RoutesProvider.unavailable(cause, ['NoRouteFoundError'])
         if (!unavailable) throw cause
         return RoutesProvider.unavailableResult({
@@ -117,6 +128,8 @@ export declare namespace rhino {
     fetch?: RoutesProvider.Fetch | undefined
     /** Clock override for deterministic tests. */
     now?: (() => Date) | undefined
+    /** Store used to coordinate provider-reported cooldowns. */
+    rateLimitStore?: Store.Store | undefined
   }
 }