tapimo 0.7.1 → 0.8.0

package/dist/internal/funding/providers/relay.js

@@ -0,0 +1,871 @@
+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 = (input, init) => globalThis.fetch(input, init);
+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',
+];
+// Bound provider statuses before using them as metric tags.
+const webhookStatuses = [
+    'depositing',
+    'failure',
+    'fallback',
+    'pending',
+    'refund',
+    'submitted',
+    'success',
+    'waiting',
+];
+var schema;
+(function (schema) {
+    const Decimal = z.union([
+        z.string().check(z.regex(/^\d+(\.\d+)?$/)),
+        z.pipe(z.number().check(z.nonnegative()), z.transform((value) => String(value))),
+    ]);
+    const Integer = z.union([
+        z.number().check(z.int(), z.nonnegative()),
+        z.pipe(z.pipe(z.string().check(z.regex(/^\d+$/)), z.transform((value) => Number(value))), z.number().check(z.int(), z.nonnegative())),
+    ]);
+    schema.Quote = z.object({
+        details: z.optional(z.object({
+            currencyOut: z.optional(z.object({
+                amount: z.optional(Decimal),
+                minimumAmount: z.optional(Decimal),
+            })),
+            timeEstimate: z.optional(Integer),
+        })),
+    });
+    const StepCall = z.object({
+        chainId: Integer,
+        data: z.string().check(z.regex(/^0x[0-9a-fA-F]*$/)),
+        from: z.string(),
+        to: z.string().check(z.regex(/^0x[0-9a-fA-F]{40}$/)),
+        value: z.optional(z.string().check(z.regex(/^\d+$/))),
+    });
+    const StepItem = z.object({
+        check: z.optional(z.object({ endpoint: z.string() })),
+        data: StepCall,
+    });
+    const Step = z.object({
+        depositAddress: z.optional(z.string()),
+        id: z.string(),
+        items: z.optional(z.array(StepItem)),
+        kind: z.string(),
+        requestId: z.optional(z.string()),
+    });
+    schema.PreparedQuote = z.object({
+        details: z.object({
+            currencyIn: z.object({ amount: Decimal }),
+            currencyOut: z.object({ amount: Decimal, minimumAmount: Decimal }),
+            timeEstimate: z.optional(Integer),
+        }),
+        fees: z.optional(z.object({
+            relayer: z.optional(z.object({ amount: Decimal })),
+        })),
+        steps: z.array(Step),
+    });
+    schema.DepositAddress = z.object({
+        details: schema.PreparedQuote.shape.details,
+        fees: schema.PreparedQuote.shape.fees,
+        steps: z.array(z.object({
+            depositAddress: z.optional(z.string()),
+            items: z.optional(z.array(z.object({
+                check: z.optional(z.object({ endpoint: z.string() })),
+            }))),
+            requestId: z.optional(z.string()),
+        })),
+    });
+    schema.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}$/)))),
+        })),
+    });
+    schema.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}$/)),
+        }),
+    });
+    schema.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({
+        txHash: z.string().check(z.minLength(1)),
+    });
+    schema.Requests = z.object({
+        continuation: z.optional(z.string().check(z.minLength(1))),
+        requests: z.array(z.object({
+            createdAt: z.iso.datetime(),
+            data: z.optional(z.object({
+                outTxs: z.optional(z.array(RequestTransaction)),
+            })),
+            depositAddress: z.optional(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(),
+        })),
+    });
+    schema.WebhookPayload = z.object({
+        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'),
+    });
+})(schema || (schema = {}));
+/** Validates a Relay request-list response and reports payload drift with field-level details. */
+export function parseDepositAddressRequests(value) {
+    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 = {}) {
+    if ((options.userAddress !== undefined &&
+        !Address.validate(options.userAddress, { strict: false })) ||
+        (options.recipientAddress !== undefined &&
+            !Address.validate(options.recipientAddress, { strict: false })))
+        throw new FundingProvider.ProviderConfigurationError();
+    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;
+        const verify = (input) => verifyWebhook(webhookOptions(input, apiKey));
+        return {
+            async receive(input) {
+                const receivedAt = now().toISOString();
+                const hint = (() => {
+                    try {
+                        return verify(input);
+                    }
+                    catch (cause) {
+                        webhook.onResult?.(cause instanceof FundingProvider.WebhookAuthenticationError
+                            ? 'authentication_failed'
+                            : 'payload_invalid');
+                        throw cause;
+                    }
+                })();
+                if (!hint.address) {
+                    webhook.onResult?.('ignored');
+                    return { type: 'ignored' };
+                }
+                const database = Db.get(webhook.db);
+                const address = await FundingDepositAddresses.getByProviderAddress(database, {
+                    address: hint.address,
+                    providerId: 'relay',
+                });
+                if (!address) {
+                    webhook.onResult?.('unknown_address');
+                    return { type: 'unknown_address' };
+                }
+                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');
+                    throw cause;
+                }
+                webhook.onResult?.('queued');
+                return { addressId: address.id, type: 'queued' };
+            },
+            verify,
+        };
+    })();
+    return FundingProvider.from({
+        id: 'relay',
+        name: 'Relay',
+        ...(webhook ? { webhook } : {}),
+        async createDepositAddress({ amount, candidate, recipient, refundAddress, subsidize }, signal) {
+            if (subsidize &&
+                (!options.subsidies ||
+                    !Subsidy.supports(options.subsidies, {
+                        amount,
+                        destinationToken: candidate.destinationToken,
+                        sourceToken: candidate.sourceToken,
+                    })))
+                throw new FundingProvider.ProviderUnavailableError();
+            const quote = await (async () => {
+                try {
+                    return await FundingProvider.requestJson(endpoint, {
+                        body: {
+                            amount,
+                            destinationChainId: relayChainId(candidate.route.destination.chain),
+                            destinationCurrency: candidate.destinationToken.address,
+                            originChainId: relayChainId(candidate.route.source.chain),
+                            originCurrency: candidate.sourceToken.address,
+                            recipient,
+                            refundTo: refundAddress,
+                            subsidizeFees: subsidize,
+                            tradeType: 'EXACT_INPUT',
+                            useDepositAddress: true,
+                            user: refundAddress,
+                        },
+                        fetch,
+                        headers: options.apiKey ? { 'x-api-key': options.apiKey } : undefined,
+                        method: 'POST',
+                        signal,
+                    });
+                }
+                catch (cause) {
+                    if (FundingProvider.unavailable(cause, ['NO_QUOTES', 'NO_ROUTE', 'UNSUPPORTED_ROUTE']))
+                        throw new FundingProvider.ProviderUnavailableError();
+                    throw cause;
+                }
+            })();
+            const parsed = schema.DepositAddress.safeParse(quote);
+            if (!parsed.success)
+                throw new FundingProvider.ProviderPayloadError();
+            if (parsed.data.details.currencyIn.amount !== amount)
+                throw new FundingProvider.ProviderPayloadError();
+            const step = parsed.data.steps.find((candidate) => candidate.depositAddress && candidate.requestId);
+            if (!step?.depositAddress || !step.requestId)
+                throw new FundingProvider.ProviderPayloadError();
+            const checkEndpoint = step.items?.find((item) => item.check)?.check?.endpoint;
+            const providerFee = parsed.data.fees?.relayer?.amount;
+            return {
+                address: step.depositAddress,
+                correlation: {
+                    ...(checkEndpoint ? { checkEndpoint } : {}),
+                    requestId: step.requestId,
+                },
+                destinationAmount: parsed.data.details.currencyOut.amount,
+                destinationAmountMin: parsed.data.details.currencyOut.minimumAmount,
+                fees: providerFee && BigInt(providerFee) > 0n ? [{ amount: providerFee, side: 'source' }] : [],
+                sampledAt: now().toISOString(),
+            };
+        },
+        async getQuote({ candidate, route }, signal) {
+            if (options.userAddress === undefined)
+                return FundingProvider.unavailableResult({
+                    detail: 'relay:quote-v2',
+                    message: 'QUOTE_USER_NOT_CONFIGURED',
+                    now: now(),
+                    source: 'providerQuote',
+                });
+            const destinationChainId = relayChainId(route.destination.chain);
+            const sourceChainId = relayChainId(route.source.chain);
+            try {
+                const quote = await FundingProvider.requestJson(endpoint, {
+                    body: {
+                        amount: candidate.sourceAmount.amount,
+                        destinationChainId,
+                        destinationCurrency: candidate.destinationToken.address,
+                        originChainId: sourceChainId,
+                        originCurrency: candidate.sourceToken.address,
+                        recipient: options.recipientAddress ?? options.userAddress,
+                        tradeType: 'EXACT_INPUT',
+                        user: options.userAddress,
+                    },
+                    fetch,
+                    headers: options.apiKey ? { 'x-api-key': options.apiKey } : undefined,
+                    method: 'POST',
+                    signal,
+                });
+                const parsed = schema.Quote.safeParse(quote);
+                if (!parsed.success)
+                    throw new FundingProvider.ProviderPayloadError();
+                const destinationAmount = parsed.data.details?.currencyOut?.amount;
+                const status = destinationAmount
+                    ? { status: 'available', tier: 'liquid' }
+                    : { status: 'unknown', tier: 'unknown' };
+                return {
+                    destinationAmountMin: parsed.data.details?.currencyOut?.minimumAmount,
+                    destinationAmount,
+                    quality: {
+                        estimatedSeconds: parsed.data.details?.timeEstimate,
+                        liquiditySource: 'providerQuote',
+                        sourceDetail: 'relay:quote-v2',
+                        tier: status.tier,
+                    },
+                    sampledAt: now().toISOString(),
+                    status: status.status,
+                };
+            }
+            catch (cause) {
+                const unavailable = FundingProvider.unavailable(cause, [
+                    'NO_QUOTES',
+                    'NO_ROUTE',
+                    'UNSUPPORTED_ROUTE',
+                ]);
+                if (!unavailable)
+                    throw cause;
+                return FundingProvider.unavailableResult({
+                    detail: 'relay:quote-v2',
+                    message: unavailable,
+                    now: now(),
+                    source: 'providerQuote',
+                });
+            }
+        },
+        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 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.
+            if (method !== 'transaction' || mode !== 'exactSource')
+                throw new FundingProvider.ProviderConfigurationError();
+            const quote = await (async () => {
+                try {
+                    return await FundingProvider.requestJson(endpoint, {
+                        body: {
+                            amount: candidate.sourceAmount.amount,
+                            destinationChainId: Number(FundingChain.eip155Id(candidate.route.destination.chain)),
+                            destinationCurrency: candidate.destinationToken.address,
+                            originChainId: Number(FundingChain.eip155Id(candidate.route.source.chain)),
+                            originCurrency: candidate.sourceToken.address,
+                            recipient,
+                            ...(slippageBps !== undefined ? { slippageTolerance: String(slippageBps) } : {}),
+                            tradeType: 'EXACT_INPUT',
+                            user: sender,
+                        },
+                        fetch,
+                        headers: options.apiKey ? { 'x-api-key': options.apiKey } : undefined,
+                        method: 'POST',
+                        signal,
+                    });
+                }
+                catch (cause) {
+                    if (FundingProvider.unavailable(cause, ['NO_QUOTES', 'NO_ROUTE', 'UNSUPPORTED_ROUTE']))
+                        throw new FundingProvider.ProviderUnavailableError();
+                    throw cause;
+                }
+            })();
+            const parsed = schema.PreparedQuote.safeParse(quote);
+            if (!parsed.success)
+                throw new FundingProvider.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();
+            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));
+            for (const item of items)
+                if (item.data.chainId !== sourceChainId ||
+                    item.data.from.toLowerCase() !== sender.toLowerCase())
+                    throw new FundingProvider.ProviderPayloadError();
+            const checkEndpoint = items.find((item) => item.check)?.check?.endpoint;
+            // Relay's `relayer` fee is the solver's total source-side charge (gas
+            // plus service); it surfaces as the transfer's provider fee.
+            const providerFee = fees?.relayer?.amount;
+            return {
+                action: {
+                    calls: items.map((item) => ({
+                        data: item.data.data,
+                        to: item.data.to,
+                        value: Hex.fromNumber(BigInt(item.data.value ?? '0')),
+                    })),
+                    type: 'evm:calls',
+                },
+                correlation: { ...(checkEndpoint ? { checkEndpoint } : {}), requestId },
+                fees: providerFee && BigInt(providerFee) > 0n ? [{ amount: providerFee, side: 'source' }] : [],
+                destinationAmountMin: details.currencyOut.minimumAmount,
+                destinationAmount: details.currencyOut.amount,
+                quality: {
+                    ...(details.timeEstimate !== undefined ? { estimatedSeconds: details.timeEstimate } : {}),
+                    liquiditySource: 'providerQuote',
+                    sourceDetail: 'relay:quote-v2',
+                    tier: 'liquid',
+                },
+                sampledAt: now().toISOString(),
+            };
+        },
+    });
+}
+function createDepositAddressObserver(options) {
+    let chainsExpiresAt = 0;
+    let chainsPromise;
+    let urlsExpiresAt = 0;
+    let urlsPromise;
+    const getChains = (signal) => {
+        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([...catalog.chainsByKey.values()].map((chain) => [
+            chain.id,
+            Evidence.resolveRpcUrls({
+                chain,
+                defaultChainId: options.defaultChainId ?? Viem.defaultChainId,
+                rpcUrlEnv: options.rpcUrlEnv,
+            }),
+        ])))
+            .catch((cause) => {
+            urlsExpiresAt = 0;
+            urlsPromise = undefined;
+            throw cause;
+        });
+        return urlsPromise;
+    };
+    return async (parameters, signal) => {
+        if (!deliveryObservationStatuses.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, depository)) ||
+            (correlation?.solver &&
+                !solvers.some((solver) => Address.isEqual(solver, correlation.solver))))
+            return { type: 'unsupported' };
+        const depositor = (correlation?.depositor ?? parameters.refundAddress);
+        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,
+            });
+            if (sourceReceipt.status !== 'success' || sourceReceipt.blockNumber === null)
+                return undefined;
+            const sourceHead = await getBlockNumber(sourceClient, { cacheTime: 0 });
+            const sweepLogs = await getLogs(sourceClient, {
+                address: depository,
+                event: relayErc20DepositEvent,
+                fromBlock: sourceReceipt.blockNumber,
+                toBlock: minimum(sourceHead, sourceReceipt.blockNumber + sourceSweepForwardBlocks),
+            });
+            const observations = [];
+            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) ||
+                    event.amount !== BigInt(parameters.source.amount) ||
+                    (correlation?.orderId && !Hex.isEqual(event.id, correlation.orderId)))
+                    continue;
+                const transaction = await getTransaction(sourceClient, { hash: log.transactionHash });
+                const call = decodeRelayErc20Deposit(transaction.input);
+                if (!call ||
+                    !Address.isEqual(transaction.from, parameters.address) ||
+                    !transaction.to ||
+                    !Address.isEqual(transaction.to, depository) ||
+                    !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,
+            args: { to: parameters.recipient },
+            event: transferEvent,
+            fromBlock: destinationHead > deliveryBackfillBlocks ? destinationHead - deliveryBackfillBlocks : 0n,
+            toBlock: destinationHead,
+        });
+        const solverAddresses = (correlation?.solver ? [correlation.solver] : solvers).map((address) => address);
+        const correlatedTransactionHashes = [];
+        const uncorrelatedTransactionHashes = [];
+        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) ||
+                !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) ||
+                !Address.isEqual(call.recipient, event.to) ||
+                call.amount !== event.value ||
+                (call.orderId && !Hex.isEqual(call.orderId, sourceObservation.orderId)))
+                continue;
+            if (call.orderId)
+                correlatedTransactionHashes.push(log.transactionHash);
+            else
+                uncorrelatedTransactionHashes.push(log.transactionHash);
+        }
+        const destinationTransactionHashes = (() => {
+            if (correlatedTransactionHashes.length > 0)
+                return correlatedTransactionHashes;
+            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) {
+    const endpoint = new URL(options.baseUrl ?? defaultBaseUrl);
+    endpoint.pathname = `${endpoint.pathname.replace(/\/+$/, '')}/chains`;
+    return endpoint;
+}
+function decodeRelayErc20Deposit(data) {
+    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) {
+    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));
+        return {
+            amount,
+            ...(data.length > encodedLength
+                ? { orderId: `0x${data.slice(encodedLength)}` }
+                : {}),
+            recipient,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function decodeEvent(abiEvent, log) {
+    try {
+        return AbiEvent.decode(abiEvent, log);
+    }
+    catch {
+        return undefined;
+    }
+}
+function jsonRpcClient(options) {
+    return createClient({
+        transport: fallback(options.urls.map((url) => {
+            const transport = RpcTransport.fromHttp(url, { fetchFn: options.fetch });
+            return custom(transport, { retryCount: 0 });
+        })),
+    });
+}
+function minimum(left, right) {
+    return left < right ? left : right;
+}
+function relayEvmChain(chains, chain) {
+    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]));
+}
+function verifyWebhook(options) {
+    const timestamp = Number(options.timestamp);
+    if (!Number.isSafeInteger(timestamp))
+        throw new WebhookSignatureError();
+    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(Hex.fromString(options.secret), Hex.fromString(`${options.timestamp}.${options.body}`)).slice(2);
+    if (!timingSafeEqual(expected, options.signature))
+        throw new WebhookSignatureError();
+    const payload = (() => {
+        try {
+            return JSON.parse(options.body);
+        }
+        catch {
+            throw new WebhookPayloadError();
+        }
+    })();
+    const parsed = schema.WebhookPayload.safeParse(payload);
+    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),
+    };
+}
+function webhookOptions(input, secret) {
+    const signature = input.headers.get('x-signature-sha256');
+    const timestamp = input.headers.get('x-signature-timestamp');
+    if (!signature || !timestamp)
+        throw new WebhookSignatureError();
+    return { body: input.body, secret, signature, timestamp };
+}
+function quoteEndpoint(options) {
+    const endpoint = new URL(options.baseUrl ?? defaultBaseUrl);
+    endpoint.pathname = `${endpoint.pathname.replace(/\/+$/, '')}/quote/v2`;
+    return endpoint;
+}
+function requestsEndpoint(options) {
+    const endpoint = new URL(options.baseUrl ?? defaultBaseUrl);
+    endpoint.pathname = `${endpoint.pathname.replace(/\/+$/, '')}/requests/v3`;
+    return endpoint;
+}
+function timingSafeEqual(left, right) {
+    if (left.length !== right.length)
+        return false;
+    let mismatch = 0;
+    for (let index = 0; index < left.length; index++)
+        mismatch |= left.charCodeAt(index) ^ right.charCodeAt(index);
+    return mismatch === 0;
+}
+function webhookStatus(status) {
+    return webhookStatuses.includes(status) ? status : 'unknown';
+}
+function webhookTimestamp(value) {
+    try {
+        return new Date(value).toISOString();
+    }
+    catch {
+        throw new WebhookPayloadError();
+    }
+}
+function relayChainId(chain) {
+    if (chain.id.startsWith('eip155:'))
+        return Number(FundingChain.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();
+}
+/** Relay webhook signature is missing, stale, or invalid. */
+export class WebhookSignatureError extends FundingProvider.WebhookAuthenticationError {
+    name = 'Funding.Provider.Relay.WebhookSignatureError';
+}
+/** Relay webhook body does not match the expected status event shape. */
+export class WebhookPayloadError extends FundingProvider.WebhookPayloadError {
+    name = 'Funding.Provider.Relay.WebhookPayloadError';
+}
+//# sourceMappingURL=relay.js.map