tapimo 0.7.2 → 0.9.0

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

@@ -1,15 +1,55 @@
-import { Address, Hash, Hex } from 'ox'
+import { AbiEvent, AbiFunction, Address, Hash, Hex, RpcTransport } from 'ox'
+import { createClient, custom, fallback } from 'viem'
+import { getBlockNumber, getLogs, getTransaction, getTransactionReceipt } from 'viem/actions'
 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 Viem from '../../Viem.js'
+import * as FundingCatalog from '../Catalog.js'
 import * as FundingChain from '../Chain.js'
+import * as Evidence from '../Evidence.js'
 import * as FundingProvider 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 webhookSignatureToleranceSeconds = 300
+const deliveryBackfillBlocks = 256n
+const relayChainsCacheTtlMs = 60_000
+const sourceSweepForwardBlocks = 256n
+const depositErc20FullAllowance = AbiFunction.from(
+  'function depositErc20(address depositor,address token,bytes32 id)',
+)
+const depositErc20WithAmount = AbiFunction.from(
+  'function depositErc20(address depositor,address token,uint256 amount,bytes32 id)',
+)
+const relayErc20DepositEvent = AbiEvent.from(
+  'event RelayErc20Deposit(address from, address token, uint256 amount, bytes32 id)',
+)
+const relayTransfer = AbiFunction.from('function transfer(address recipient,uint256 amount)')
+const transferEvent = AbiEvent.from(
+  'event Transfer(address indexed from, address indexed to, uint256 value)',
+)
+const webhookSignatureToleranceMs = 300_000
+const deliveryObservationStatuses = [
+  'depositing',
+  'pending',
+  'submitted',
+  'success',
+  'waiting',
+] as const
+// Bound provider statuses before using them as metric tags.
+const webhookStatuses = [
+  'depositing',
+  'failure',
+  'fallback',
+  'pending',
+  'refund',
+  'submitted',
+  'success',
+  'waiting',
+] as const
 
 namespace schema {
   const Decimal = z.union([
@@ -98,8 +138,44 @@ namespace schema {
     ),
   })
 
+  export const Chains = z.object({
+    chains: z.array(
+      z.object({
+        id: Integer,
+        protocol: z.optional(
+          z.object({
+            v2: z.optional(
+              z.object({
+                depository: z.string().check(z.regex(/^0x[0-9a-fA-F]{40}$/)),
+              }),
+            ),
+          }),
+        ),
+        solverAddresses: z.optional(z.array(z.string().check(z.regex(/^0x[0-9a-fA-F]{40}$/)))),
+      }),
+    ),
+  })
+
+  export const DeliveryObservation = z.object({
+    relay: z.object({
+      orderId: z.string().check(z.regex(/^0x[0-9a-fA-F]{64}$/)),
+      sourceDepository: z.string().check(z.regex(/^0x[0-9a-fA-F]{40}$/)),
+      sourceObservedAt: z.iso.datetime(),
+      sourceSweepTransactionHash: z.string().check(z.regex(/^0x[0-9a-fA-F]{64}$/)),
+    }),
+  })
+
+  export const RequestCorrelation = z.object({
+    relay: z.object({
+      depositor: z.optional(z.string().check(z.regex(/^0x[0-9a-fA-F]{40}$/))),
+      depository: z.optional(z.string().check(z.regex(/^0x[0-9a-fA-F]{40}$/))),
+      orderId: z.optional(z.string().check(z.regex(/^0x[0-9a-fA-F]{64}$/))),
+      solver: z.optional(z.string().check(z.regex(/^0x[0-9a-fA-F]{40}$/))),
+    }),
+  })
+
   const RequestTransaction = z.object({
-    hash: z.string().check(z.minLength(1)),
+    txHash: z.string().check(z.minLength(1)),
   })
 
   export const Requests = z.object({
@@ -113,11 +189,35 @@ namespace schema {
           }),
         ),
         depositAddress: z.optional(
-          z.object({
-            depositTxHash: z.optional(z.string().check(z.minLength(1))),
-          }),
+          z.nullable(
+            z.object({
+              depositTxHash: z.optional(z.nullable(z.string().check(z.minLength(1)))),
+            }),
+          ),
         ),
         id: z.string().check(z.minLength(1)),
+        protocol: z.optional(
+          z.nullable(
+            z.object({
+              deposit: z.optional(
+                z.object({
+                  origin: z.optional(
+                    z.object({
+                      depositor: z.optional(z.string().check(z.regex(/^0x[0-9a-fA-F]{40}$/))),
+                      depository: z.optional(z.string().check(z.regex(/^0x[0-9a-fA-F]{40}$/))),
+                    }),
+                  ),
+                }),
+              ),
+              orderId: z.optional(z.string().check(z.regex(/^0x[0-9a-fA-F]{64}$/))),
+              solver: z.optional(
+                z.object({
+                  address: z.optional(z.string().check(z.regex(/^0x[0-9a-fA-F]{40}$/))),
+                }),
+              ),
+            }),
+          ),
+        ),
         status: z.string().check(z.minLength(1)),
         updatedAt: z.iso.datetime(),
       }),
@@ -128,11 +228,20 @@ namespace schema {
     data: z.object({
       depositAddress: z.nullable(z.object({ address: z.string().check(z.minLength(1)) })),
       requestId: z.optional(z.string().check(z.minLength(1))),
+      status: z.string().check(z.minLength(1)),
+      updatedAt: z.number().check(z.int(), z.nonnegative()),
     }),
     event: z.literal('request.status.updated'),
   })
 }
 
+/** 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))
+  return parsed.data
+}
+
 /** Creates a Relay funding provider backed by `/quote/v2`. */
 export function relay(options: relay.Options = {}): FundingProvider.Provider<'relay'> {
   if (
@@ -146,6 +255,15 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
   const endpoint = quoteEndpoint(options)
   const fetch = options.fetch ?? defaultFetch
   const now = options.now ?? (() => new Date())
+  const observeDepositAddressRequest = options.observation
+    ? createDepositAddressObserver({
+        ...options.observation,
+        ...(options.apiKey ? { apiKey: options.apiKey } : {}),
+        ...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+        fetch,
+        now,
+      })
+    : undefined
   const webhook = (() => {
     if (!options.apiKey || !options.webhook) return undefined
     const { apiKey, webhook } = options
@@ -153,6 +271,7 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
       verifyWebhook(webhookOptions(input, apiKey))
     return {
       async receive(input: FundingProvider.Webhook.receive.Parameters) {
+        const receivedAt = now().toISOString()
         const hint = (() => {
           try {
             return verify(input)
@@ -169,7 +288,8 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
           webhook.onResult?.('ignored')
           return { type: 'ignored' as const }
         }
-        const address = await FundingDepositAddresses.getByProviderAddress(Db.get(webhook.db), {
+        const database = Db.get(webhook.db)
+        const address = await FundingDepositAddresses.getByProviderAddress(database, {
           address: hint.address,
           providerId: 'relay',
         })
@@ -177,11 +297,33 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
           webhook.onResult?.('unknown_address')
           return { type: 'unknown_address' as const }
         }
+        if (hint.requestId)
+          await FundingDepositRequestObservations.observeWebhook(database, {
+            depositAddressId: address.id,
+            providerRequestId: hint.requestId,
+            receivedAt,
+          }).catch((cause) => {
+            webhook.onResult?.('observation_failed')
+            throw cause
+          })
         try {
+          const webhookTiming = (() => {
+            if (!hint.providerStatus || !hint.providerUpdatedAt || !hint.requestId || !hint.sentAt)
+              return undefined
+            return {
+              enqueuedAt: now().toISOString(),
+              providerStatus: hint.providerStatus,
+              providerUpdatedAt: hint.providerUpdatedAt,
+              receivedAt,
+              sentAt: hint.sentAt,
+            }
+          })()
           await webhook.dispatch({
             addressId: address.id,
             ...(hint.requestId ? { requestId: hint.requestId } : {}),
+            trigger: 'webhook',
             type: 'funding:deposit-address:reconcile',
+            ...(webhookTiming ? { webhookTiming } : {}),
           })
         } catch (cause) {
           webhook.onResult?.('enqueue_failed')
@@ -323,10 +465,8 @@ 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')
-      }
+      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')
@@ -337,22 +477,41 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
         method: 'GET',
         signal,
       })
-      const parsed = schema.Requests.safeParse(response)
-      if (!parsed.success) throw new FundingProvider.ProviderPayloadError()
+      const parsed = parseDepositAddressRequests(response)
       return {
-        ...(parsed.data.continuation ? { continuation: parsed.data.continuation } : {}),
-        requests: parsed.data.requests.map((request) => ({
-          createdAt: new Date(request.createdAt).toISOString(),
-          destinationTransactionHashes: request.data?.outTxs?.map((tx) => tx.hash) ?? [],
-          id: request.id,
-          sourceTransactionHashes: request.depositAddress?.depositTxHash
-            ? [request.depositAddress.depositTxHash]
-            : [],
-          status: request.status,
-          updatedAt: new Date(request.updatedAt).toISOString(),
-        })),
+        ...(parsed.continuation ? { continuation: parsed.continuation } : {}),
+        requests: parsed.requests.map((request) => {
+          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: request.data?.outTxs?.map((tx) => tx.txHash) ?? [],
+            id: request.id,
+            ...(correlation ? { providerState: correlation } : {}),
+            sourceTransactionHashes: request.depositAddress?.depositTxHash
+              ? [request.depositAddress.depositTxHash]
+              : [],
+            status: request.status,
+            updatedAt: new Date(request.updatedAt).toISOString(),
+          }
+        }),
       }
     },
+    ...(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.
@@ -445,6 +604,8 @@ export declare namespace relay {
     fetch?: FundingProvider.Fetch | undefined
     /** Clock override for deterministic tests. */
     now?: (() => Date) | undefined
+    /** EVM chain evidence used to accelerate authenticated provider delivery. */
+    observation?: Observation | undefined
     /** Optional recipient override; defaults to `userAddress`. */
     recipientAddress?: string | undefined
     /** Deposit subsidy policy enabled for this integration. */
@@ -455,6 +616,16 @@ export declare namespace relay {
     webhook?: Webhook | undefined
   }
 
+  /** Chain evidence configuration for Relay delivery observation. */
+  type Observation = {
+    /** Authoritative funding database or per-request database factory. */
+    db: Db.Source
+    /** Tempo chain that receives a shared RPC URL override. */
+    defaultChainId?: Viem.ChainId | undefined
+    /** Shared or per-EVM-chain RPC URL environment value. */
+    rpcUrlEnv?: Viem.UrlResolver | undefined
+  }
+
   /** Authenticated Relay webhook integration attached to a provider instance. */
   type Webhook = {
     /** Authoritative funding database or per-request database factory. */
@@ -470,11 +641,332 @@ export declare namespace relay {
     | 'authentication_failed'
     | 'enqueue_failed'
     | 'ignored'
+    | 'observation_failed'
     | 'payload_invalid'
     | 'queued'
     | 'unknown_address'
 }
 
+type DepositAddressObserverOptions = relay.Observation & {
+  apiKey?: string | undefined
+  baseUrl?: string | undefined
+  fetch: FundingProvider.Fetch
+  now: () => Date
+}
+
+type RelayChain = z.output<typeof schema.Chains>['chains'][number]
+type RelayDeliveryObservation = z.output<typeof schema.DeliveryObservation>['relay']
+
+function createDepositAddressObserver(
+  options: DepositAddressObserverOptions,
+): NonNullable<FundingProvider.Provider['observeDepositAddressRequest']> {
+  let chainsExpiresAt = 0
+  let chainsPromise: Promise<readonly RelayChain[]> | undefined
+  let urlsExpiresAt = 0
+  let urlsPromise: Promise<ReadonlyMap<string, readonly string[]>> | undefined
+  const getChains = (signal: AbortSignal) => {
+    if (chainsPromise && options.now().getTime() < chainsExpiresAt) return chainsPromise
+    chainsExpiresAt = options.now().getTime() + relayChainsCacheTtlMs
+    chainsPromise = FundingProvider.requestJson(chainsEndpoint(options), {
+      fetch: options.fetch,
+      headers: options.apiKey ? { 'x-api-key': options.apiKey } : undefined,
+      signal,
+    })
+      .then((value) => schema.Chains.parse(value).chains)
+      .catch((cause) => {
+        chainsExpiresAt = 0
+        chainsPromise = undefined
+        throw cause
+      })
+    return chainsPromise
+  }
+  const getUrls = () => {
+    if (urlsPromise && options.now().getTime() < urlsExpiresAt) return urlsPromise
+    urlsExpiresAt = options.now().getTime() + relayChainsCacheTtlMs
+    urlsPromise = FundingCatalog.read(Db.get(options.db))
+      .then(
+        (catalog) =>
+          new Map<string, readonly string[]>(
+            [...catalog.chainsByKey.values()].map(
+              (chain) =>
+                [
+                  chain.id,
+                  Evidence.resolveRpcUrls({
+                    chain,
+                    defaultChainId: options.defaultChainId ?? Viem.defaultChainId,
+                    rpcUrlEnv: options.rpcUrlEnv,
+                  }),
+                ] as const,
+            ),
+          ),
+      )
+      .catch((cause) => {
+        urlsExpiresAt = 0
+        urlsPromise = undefined
+        throw cause
+      })
+    return urlsPromise
+  }
+
+  return async (parameters, signal) => {
+    if (
+      parameters.request &&
+      !(deliveryObservationStatuses as readonly string[]).includes(parameters.request.status)
+    )
+      return { type: 'unsupported' }
+    if (parameters.sourceChain.kind !== 'evm' || parameters.destinationChain.kind !== 'evm')
+      return { type: 'unsupported' }
+    if (
+      !Address.validate(parameters.address, { strict: false }) ||
+      !Address.validate(parameters.destinationToken.address, { strict: false }) ||
+      !Address.validate(parameters.recipient, { strict: false }) ||
+      !Address.validate(parameters.refundAddress, { strict: false }) ||
+      !Address.validate(parameters.sourceToken.address, { strict: false }) ||
+      !Hash.validate(parameters.source.transactionHash)
+    )
+      return { type: 'unsupported' }
+
+    const [chains, urls] = await Promise.all([getChains(signal), getUrls()])
+    const sourceChain = relayEvmChain(chains, parameters.sourceChain)
+    const destinationChain = relayEvmChain(chains, parameters.destinationChain)
+    const sourceUrls = urls.get(parameters.sourceChain.id)
+    const destinationUrls = urls.get(parameters.destinationChain.id)
+    const depository = sourceChain?.protocol?.v2?.depository
+    const solvers = destinationChain?.solverAddresses
+    if (
+      !depository ||
+      !solvers ||
+      solvers.length === 0 ||
+      !sourceUrls?.length ||
+      !destinationUrls?.length
+    )
+      return { type: 'unsupported' }
+
+    const parsedCorrelation = schema.RequestCorrelation.safeParse(parameters.request?.providerState)
+    const correlation = parsedCorrelation.success ? parsedCorrelation.data.relay : undefined
+    if (
+      (correlation?.depository &&
+        !Address.isEqual(
+          correlation.depository as Address.Address,
+          depository as Address.Address,
+        )) ||
+      (correlation?.solver &&
+        !solvers.some((solver) =>
+          Address.isEqual(solver as Address.Address, correlation.solver as Address.Address),
+        ))
+    )
+      return { type: 'unsupported' }
+    const depositor = (correlation?.depositor ?? parameters.refundAddress) as Address.Address
+
+    const stored = schema.DeliveryObservation.safeParse(parameters.providerState)
+    const sourceObservation = await (async () => {
+      if (stored.success) return stored.data.relay
+      const sourceClient = jsonRpcClient({ fetch: options.fetch, urls: sourceUrls })
+      const sourceReceipt = await getTransactionReceipt(sourceClient, {
+        hash: parameters.source.transactionHash as Hex.Hex,
+      })
+      if (sourceReceipt.status !== 'success' || sourceReceipt.blockNumber === null) return undefined
+      const sourceHead = await getBlockNumber(sourceClient, { cacheTime: 0 })
+      const sweepLogs = await getLogs(sourceClient, {
+        address: depository as Address.Address,
+        event: relayErc20DepositEvent,
+        fromBlock: sourceReceipt.blockNumber,
+        toBlock: minimum(sourceHead, sourceReceipt.blockNumber + sourceSweepForwardBlocks),
+      })
+      const observations: RelayDeliveryObservation[] = []
+      for (const log of sweepLogs) {
+        if (!log.transactionHash) continue
+        const event = decodeEvent(relayErc20DepositEvent, log)
+        if (
+          !event ||
+          !Address.isEqual(event.from, depositor) ||
+          !Address.isEqual(event.token, parameters.sourceToken.address as Address.Address) ||
+          event.amount !== BigInt(parameters.source.amount) ||
+          (correlation?.orderId && !Hex.isEqual(event.id, correlation.orderId as Hex.Hex))
+        )
+          continue
+        const transaction = await getTransaction(sourceClient, { hash: log.transactionHash })
+        const call = decodeRelayErc20Deposit(transaction.input)
+        if (
+          !call ||
+          !Address.isEqual(transaction.from, parameters.address as Address.Address) ||
+          !transaction.to ||
+          !Address.isEqual(transaction.to, depository as Address.Address) ||
+          !Address.isEqual(call.depositor, event.from) ||
+          !Address.isEqual(call.token, event.token) ||
+          (call.amount !== undefined && call.amount !== event.amount) ||
+          !Hex.isEqual(call.id, event.id)
+        )
+          continue
+        observations.push({
+          orderId: event.id,
+          sourceDepository: depository,
+          sourceObservedAt: options.now().toISOString(),
+          sourceSweepTransactionHash: log.transactionHash,
+        })
+      }
+      return observations.length === 1 ? observations[0] : undefined
+    })()
+    if (!sourceObservation) return { type: 'pending' }
+
+    const destinationClient = jsonRpcClient({ fetch: options.fetch, urls: destinationUrls })
+    const destinationHead = await getBlockNumber(destinationClient, { cacheTime: 0 })
+    const destinationLogs = await getLogs(destinationClient, {
+      address: parameters.destinationToken.address as Address.Address,
+      args: { to: parameters.recipient as Address.Address },
+      event: transferEvent,
+      fromBlock:
+        destinationHead > deliveryBackfillBlocks ? destinationHead - deliveryBackfillBlocks : 0n,
+      toBlock: destinationHead,
+    })
+    const solverAddresses = (correlation?.solver ? [correlation.solver] : solvers).map(
+      (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)
+      )
+        continue
+      const event = decodeEvent(transferEvent, log)
+      if (
+        !event ||
+        event.value === 0n ||
+        !Address.isEqual(event.to, parameters.recipient as Address.Address) ||
+        !solverAddresses.some((address) => Address.isEqual(address, event.from))
+      )
+        continue
+      const transaction = await getTransaction(destinationClient, { hash: log.transactionHash })
+      const call = decodeRelayTransfer(transaction.input)
+      if (
+        !call ||
+        !solverAddresses.some((address) => Address.isEqual(address, transaction.from)) ||
+        !Address.isEqual(event.from, transaction.from) ||
+        !transaction.to ||
+        !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))
+      )
+        continue
+      if (call.orderId) correlatedTransactionHashes.push(log.transactionHash)
+      else uncorrelatedTransactionHashes.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 providerState = { relay: sourceObservation }
+    if (destinationTransactionHashes.length === 0)
+      return {
+        providerState,
+        providerTransactionHashes: [sourceObservation.sourceSweepTransactionHash],
+        type: 'pending',
+      }
+
+    return {
+      destinationTransactionHashes,
+      providerState: {
+        relay: {
+          ...sourceObservation,
+          destinationObservedAt: options.now().toISOString(),
+        },
+      },
+      providerTransactionHashes: [
+        sourceObservation.sourceSweepTransactionHash,
+        ...destinationTransactionHashes,
+      ],
+      type: 'verified',
+    }
+  }
+}
+
+function chainsEndpoint(options: Pick<DepositAddressObserverOptions, 'baseUrl'>): URL {
+  const endpoint = new URL(options.baseUrl ?? defaultBaseUrl)
+  endpoint.pathname = `${endpoint.pathname.replace(/\/+$/, '')}/chains`
+  return endpoint
+}
+
+function decodeRelayErc20Deposit(data: Hex.Hex) {
+  const fullAllowanceLength = 2 + 2 * (4 + 32 * 3)
+  const withAmountLength = 2 + 2 * (4 + 32 * 4)
+  try {
+    if (data.length === withAmountLength) {
+      const [depositor, token, amount, id] = AbiFunction.decodeData(depositErc20WithAmount, data)
+      return { amount, depositor, id, token }
+    }
+    if (data.length === fullAllowanceLength) {
+      const [depositor, token, id] = AbiFunction.decodeData(depositErc20FullAllowance, data)
+      return { depositor, id, token }
+    }
+    return undefined
+  } catch {
+    return undefined
+  }
+}
+
+function decodeRelayTransfer(data: Hex.Hex) {
+  const encodedLength = 2 + 2 * (4 + 32 * 2)
+  if (data.length !== encodedLength && data.length !== encodedLength + 64) return undefined
+  try {
+    const [recipient, amount] = AbiFunction.decodeData(
+      relayTransfer,
+      data.slice(0, encodedLength) as Hex.Hex,
+    )
+    return {
+      amount,
+      ...(data.length > encodedLength
+        ? { orderId: `0x${data.slice(encodedLength)}` as Hex.Hex }
+        : {}),
+      recipient,
+    }
+  } catch {
+    return undefined
+  }
+}
+
+function decodeEvent<const event extends AbiEvent.AbiEvent>(
+  abiEvent: event,
+  log: { data: Hex.Hex; topics: readonly Hex.Hex[] },
+): AbiEvent.decode.ReturnType<event> | undefined {
+  try {
+    return AbiEvent.decode(abiEvent, log)
+  } catch {
+    return undefined
+  }
+}
+
+function jsonRpcClient(options: { fetch: FundingProvider.Fetch; urls: readonly string[] }) {
+  return createClient({
+    transport: fallback(
+      options.urls.map((url) => {
+        const transport = RpcTransport.fromHttp(url, { fetchFn: options.fetch })
+        return custom(transport, { retryCount: 0 })
+      }),
+    ),
+  })
+}
+
+function minimum(left: bigint, right: bigint): bigint {
+  return left < right ? left : right
+}
+
+function relayEvmChain(
+  chains: readonly RelayChain[],
+  chain: FundingProvider.ChainRef,
+): RelayChain | undefined {
+  if (chain.kind !== 'evm') return undefined
+  const match = /^eip155:(\d+)$/.exec(chain.id)
+  if (!match?.[1]) return undefined
+  return chains.find((candidate) => candidate.id === Number(match[1]))
+}
+
 type VerifyWebhookOptions = {
   body: string
   secret: string
@@ -485,8 +977,7 @@ type VerifyWebhookOptions = {
 function verifyWebhook(options: VerifyWebhookOptions): FundingProvider.Webhook.verify.ReturnType {
   const timestamp = Number(options.timestamp)
   if (!Number.isSafeInteger(timestamp)) throw new WebhookSignatureError()
-  const now = Math.floor(Date.now() / 1_000)
-  if (Math.abs(now - timestamp) > webhookSignatureToleranceSeconds)
+  if (Math.abs(Date.now() - timestamp) > webhookSignatureToleranceMs)
     throw new WebhookSignatureError()
   if (!/^[0-9a-fA-F]{64}$/.test(options.signature)) throw new WebhookSignatureError()
   const expected = Hash.hmac256(
@@ -506,7 +997,10 @@ function verifyWebhook(options: VerifyWebhookOptions): FundingProvider.Webhook.v
   if (!parsed.success) throw new WebhookPayloadError()
   return {
     address: parsed.data.data.depositAddress?.address,
+    providerStatus: webhookStatus(parsed.data.data.status),
+    providerUpdatedAt: webhookTimestamp(parsed.data.data.updatedAt),
     requestId: parsed.data.data.requestId,
+    sentAt: webhookTimestamp(timestamp),
   }
 }
 
@@ -528,7 +1022,7 @@ function quoteEndpoint(options: relay.Options): URL {
 
 function requestsEndpoint(options: relay.Options): URL {
   const endpoint = new URL(options.baseUrl ?? defaultBaseUrl)
-  endpoint.pathname = `${endpoint.pathname.replace(/\/+$/, '')}/requests/v2`
+  endpoint.pathname = `${endpoint.pathname.replace(/\/+$/, '')}/requests/v3`
   return endpoint
 }
 
@@ -540,6 +1034,18 @@ function timingSafeEqual(left: string, right: string): boolean {
   return mismatch === 0
 }
 
+function webhookStatus(status: string): string {
+  return (webhookStatuses as readonly string[]).includes(status) ? status : 'unknown'
+}
+
+function webhookTimestamp(value: number): string {
+  try {
+    return new Date(value).toISOString()
+  } catch {
+    throw new WebhookPayloadError()
+  }
+}
+
 function relayChainId(chain: FundingProvider.Chain): number {
   if (chain.id.startsWith('eip155:')) return Number(FundingChain.eip155Id(chain))
   // Relay uses a numeric chain ID for Solana instead of its CAIP-2 reference.