tapimo 0.7.1 → 0.8.0

package/dist/internal/funding/Reconciliation.js

@@ -0,0 +1,885 @@
+import { Hex } from 'ox';
+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 FundingDeposits from '../../db/tables/fundingDeposits.js';
+import * as Value from '../Value.js';
+import * as Deposit from './Deposit.js';
+import * as Provider from './Provider.js';
+import * as Subsidy from './Subsidy.js';
+const defaultBatchSize = 25;
+const defaultLeaseMs = 2 * 60_000;
+const defaultPollIntervalMs = 60_000;
+const followUpDelaySeconds = { delivery: 1, provider: 5, settlement: 2 };
+const maximumPages = 100;
+const maximumFollowUpAttempts = 6;
+/** Creates a reusable-address reconciliation tracker. */
+export function createTracker(options) {
+    const now = options.now ?? (() => new Date());
+    const batchSize = options.batchSize ?? defaultBatchSize;
+    const leaseMs = options.leaseMs ?? defaultLeaseMs;
+    const pollIntervalMs = options.pollIntervalMs ?? defaultPollIntervalMs;
+    const record = (outcome, providerId, trigger) => {
+        options.metrics?.count('funding_deposit_reconciliation_count', 1, {
+            outcome,
+            provider: providerId,
+            trigger,
+        });
+    };
+    return {
+        async reconcile(message) {
+            const database = Db.get(options.db);
+            const startedAt = now();
+            // Legacy poll messages carry a lease version; legacy webhook messages do not.
+            const trigger = (() => {
+                if (message.trigger)
+                    return message.trigger;
+                if (message.pollLeaseVersion !== undefined)
+                    return 'poll';
+                return 'webhook';
+            })();
+            const claimed = await claim(database, message, {
+                leaseUntil: new Date(startedAt.getTime() + leaseMs).toISOString(),
+                now: startedAt.toISOString(),
+            });
+            if (!claimed)
+                return { type: 'busy' };
+            const provider = options.providers.find((candidate) => candidate.id === claimed.providerId);
+            if (!provider || !Provider.canListDepositAddressRequests(provider)) {
+                await fail(database, claimed, startedAt, pollIntervalMs);
+                record('provider_unavailable', claimed.providerId, trigger);
+                return { type: 'provider_unavailable' };
+            }
+            const heartbeat = maintainLease(database, claimed, { leaseMs, now });
+            try {
+                await heartbeat.ready();
+                const requests = await listRequests(provider, {
+                    address: claimed,
+                    requestId: message.requestId,
+                    signal: options.signal,
+                });
+                if (trigger === 'poll')
+                    await FundingDepositRequestObservations.observePoll(database, {
+                        depositAddressId: claimed.id,
+                        observedAt: now().toISOString(),
+                        providerRequestIds: requests.requests.map((request) => request.id),
+                    });
+                const webhookUpdateObserved = (() => {
+                    const timing = message.webhookTiming;
+                    if (!timing)
+                        return true;
+                    if (!message.requestId)
+                        return false;
+                    // Relay can send a webhook before its requests API indexes the same update.
+                    return requests.requests.some((request) => request.id === message.requestId && request.updatedAt >= timing.providerUpdatedAt);
+                })();
+                heartbeat.assert();
+                let created = 0;
+                let updated = 0;
+                const pendingRequestIds = new Set([
+                    ...requests.pendingRequestIds,
+                    ...(message.requestId ? [message.requestId] : []),
+                ]);
+                let followUpKind;
+                for (const request of requests.requests) {
+                    const result = await reconcileRequest(database, {
+                        address: claimed,
+                        metrics: options.metrics,
+                        provider,
+                        request,
+                        signal: options.signal,
+                        subsidies: options.subsidies,
+                        trigger,
+                        verifyTransfers: options.verifyTransfers,
+                    });
+                    heartbeat.assert();
+                    created += result.created;
+                    updated += result.updated;
+                    if (result.terminal)
+                        pendingRequestIds.delete(request.id);
+                    else {
+                        pendingRequestIds.add(request.id);
+                        followUpKind = result.followUp ?? followUpKind ?? 'provider';
+                    }
+                }
+                const awaitsProvider = await FundingDeposits.hasUnattributed(database, claimed.id);
+                if (message.requestId && message.webhookTiming && !webhookUpdateObserved)
+                    pendingRequestIds.add(message.requestId);
+                if (created > 0)
+                    options.metrics?.count('funding_deposit_detection_count', created, {
+                        provider: claimed.providerId,
+                        trigger,
+                    });
+                const leaseFailure = await heartbeat.stop();
+                if (leaseFailure !== undefined)
+                    throw leaseFailure;
+                const completedAt = now();
+                const stored = await FundingDepositAddresses.completePoll(database, {
+                    id: claimed.id,
+                    lastPolledAt: completedAt.toISOString(),
+                    nextPollAt: new Date(completedAt.getTime() + pollIntervalMs).toISOString(),
+                    pollLeaseVersion: claimed.pollLeaseVersion,
+                    providerRequestIds: claimed.providerRequestIds,
+                    providerState: reconciliationState(claimed.providerState, {
+                        pendingRequestIds: [...pendingRequestIds],
+                        requests,
+                        ...(message.webhookTiming && message.requestId && webhookUpdateObserved
+                            ? {
+                                webhookTiming: {
+                                    ...message.webhookTiming,
+                                    reconciliationCompletedAt: completedAt.toISOString(),
+                                    requestId: message.requestId,
+                                },
+                            }
+                            : {}),
+                    }),
+                });
+                if (!stored)
+                    return { type: 'stale' };
+                if (pendingRequestIds.size > 0 || awaitsProvider) {
+                    const followUp = nextFollowUp(message, followUpKind ?? 'provider');
+                    if (followUp)
+                        await options
+                            .dispatch({
+                            addressId: claimed.id,
+                            followUp: followUp.state,
+                            ...(message.requestId ? { requestId: message.requestId } : {}),
+                            trigger,
+                            type: 'funding:deposit-address:reconcile',
+                            ...(message.webhookTiming && !webhookUpdateObserved
+                                ? { webhookTiming: message.webhookTiming }
+                                : {}),
+                        }, { delaySeconds: followUp.delaySeconds })
+                            .catch((cause) => {
+                            record('follow_up_enqueue_failed', claimed.providerId, trigger);
+                            throw cause;
+                        });
+                    record(followUp ? 'follow_up_enqueued' : 'follow_up_exhausted', claimed.providerId, trigger);
+                }
+                if (message.webhookTiming && webhookUpdateObserved)
+                    recordWebhookLatency(options.metrics, {
+                        completedAt,
+                        providerId: claimed.providerId,
+                        timing: message.webhookTiming,
+                    });
+                record('completed', claimed.providerId, trigger);
+                options.metrics?.histogram('funding_deposit_reconciliation_duration_ms', completedAt.getTime() - startedAt.getTime(), { provider: claimed.providerId, trigger });
+                return { created, type: 'completed', updated };
+            }
+            catch (cause) {
+                const leaseFailure = await heartbeat.stop();
+                await fail(database, claimed, now(), pollIntervalMs);
+                record('failed', claimed.providerId, trigger);
+                throw leaseFailure ?? cause;
+            }
+            finally {
+                options.metrics?.flush();
+            }
+        },
+        async tick() {
+            const database = Db.get(options.db);
+            const startedAt = now();
+            const leaseUntil = new Date(startedAt.getTime() + leaseMs).toISOString();
+            let claimed = 0;
+            let failed = 0;
+            for (const provider of options.providers) {
+                if (!Provider.canListDepositAddressRequests(provider))
+                    continue;
+                const records = await FundingDepositAddresses.claimDue(database, {
+                    leaseUntil,
+                    limit: Math.max(0, batchSize - claimed),
+                    now: startedAt.toISOString(),
+                    providerId: provider.id,
+                });
+                for (const address of records) {
+                    claimed += 1;
+                    options.metrics?.histogram('funding_deposit_poll_lag_ms', Math.max(0, startedAt.getTime() - new Date(address.nextPollAt).getTime()), { provider: provider.id });
+                    try {
+                        await options.dispatch({
+                            addressId: address.id,
+                            pollLeaseVersion: address.pollLeaseVersion,
+                            trigger: 'poll',
+                            type: 'funding:deposit-address:reconcile',
+                        });
+                        record('enqueued', provider.id, 'poll');
+                    }
+                    catch {
+                        failed += 1;
+                        await fail(database, address, startedAt, pollIntervalMs);
+                        record('enqueue_failed', provider.id, 'poll');
+                    }
+                }
+                if (claimed >= batchSize)
+                    break;
+            }
+            options.metrics?.flush();
+            return { claimed, failed };
+        },
+    };
+}
+async function claim(db, message, options) {
+    if (message.pollLeaseVersion === undefined)
+        return FundingDepositAddresses.claim(db, {
+            id: message.addressId,
+            leaseUntil: options.leaseUntil,
+            now: options.now,
+        });
+    const current = await FundingDepositAddresses.get(db, message.addressId);
+    if (!current?.pollLeaseUntil ||
+        current.pollLeaseUntil <= options.now ||
+        current.pollLeaseVersion !== message.pollLeaseVersion)
+        return undefined;
+    return current;
+}
+async function fail(db, address, now, pollIntervalMs) {
+    const delay = Math.min(pollIntervalMs * 2 ** address.pollFailureCount, 15 * 60_000);
+    return FundingDepositAddresses.failPoll(db, {
+        id: address.id,
+        nextPollAt: new Date(now.getTime() + delay).toISOString(),
+        pollLeaseVersion: address.pollLeaseVersion,
+    });
+}
+function maintainLease(db, address, options) {
+    let failure;
+    let stopped = false;
+    const extend = async () => {
+        if (stopped || failure !== undefined)
+            return;
+        const renewed = await FundingDepositAddresses.renewPoll(db, {
+            id: address.id,
+            leaseUntil: new Date(options.now().getTime() + options.leaseMs).toISOString(),
+            pollLeaseVersion: address.pollLeaseVersion,
+        });
+        if (!renewed)
+            failure = new StaleLeaseError();
+    };
+    const captureFailure = (cause) => {
+        failure = cause;
+    };
+    let renewal = extend().catch(captureFailure);
+    const timer = setInterval(() => {
+        renewal = renewal.then(extend).catch(captureFailure);
+    }, Math.max(1, Math.floor(options.leaseMs / 2)));
+    return {
+        assert() {
+            if (failure !== undefined)
+                throw failure;
+        },
+        async ready() {
+            await renewal;
+            if (failure !== undefined)
+                throw failure;
+        },
+        async stop() {
+            if (!stopped) {
+                stopped = true;
+                clearInterval(timer);
+            }
+            await renewal;
+            return failure;
+        },
+    };
+}
+async function listRequests(provider, options) {
+    const highWater = readHighWater(options.address.providerState);
+    const highWaterRequestIds = new Set(highWater.requestIds);
+    const pendingRequestIds = new Set(highWater.pendingRequestIds);
+    const requests = [];
+    let continuation;
+    for (let page = 0; page < maximumPages; page++) {
+        const result = await provider.listDepositAddressRequests({ address: options.address.address, ...(continuation ? { continuation } : {}) }, options.signal ?? new AbortController().signal);
+        requests.push(...result.requests.filter((request) => !highWater.updatedAt ||
+            request.updatedAt > highWater.updatedAt ||
+            (request.updatedAt === highWater.updatedAt &&
+                (!highWaterRequestIds.has(request.id) || pendingRequestIds.has(request.id)))));
+        const reached = result.requests.some((request) => highWater.updatedAt && request.updatedAt < highWater.updatedAt);
+        continuation = result.continuation;
+        if (!continuation || reached)
+            break;
+        if (page === maximumPages - 1)
+            throw new PaginationLimitError();
+    }
+    const observed = new Set(requests.map((request) => request.id));
+    for (const requestId of unique([
+        ...highWater.pendingRequestIds,
+        ...(options.requestId ? [options.requestId] : []),
+    ])) {
+        if (observed.has(requestId))
+            continue;
+        const result = await provider.listDepositAddressRequests({ address: options.address.address, requestId }, options.signal ?? new AbortController().signal);
+        requests.push(...result.requests);
+    }
+    const addressRequests = requests.filter((request) => !highWater.pendingRequestIds.includes(request.id));
+    const newest = addressRequests.reduce((value, request) => (!value || request.updatedAt > value ? request.updatedAt : value), highWater.updatedAt);
+    return {
+        highWaterRequestIds: newest
+            ? unique([
+                ...(newest === highWater.updatedAt ? highWater.requestIds : []),
+                ...addressRequests
+                    .filter((request) => request.updatedAt === newest)
+                    .map((request) => request.id),
+            ])
+            : [],
+        highWaterUpdatedAt: newest,
+        pendingRequestIds: highWater.pendingRequestIds,
+        requests,
+    };
+}
+function readHighWater(state) {
+    if (!state || typeof state !== 'object')
+        return { pendingRequestIds: [], requestIds: [] };
+    const reconciliation = state['reconciliation'];
+    if (!reconciliation || typeof reconciliation !== 'object')
+        return { pendingRequestIds: [], requestIds: [] };
+    const pendingRequestIds = 'pendingRequestIds' in reconciliation && Array.isArray(reconciliation.pendingRequestIds)
+        ? reconciliation.pendingRequestIds.filter((value) => typeof value === 'string')
+        : [];
+    const requestIds = 'requestIds' in reconciliation && Array.isArray(reconciliation.requestIds)
+        ? reconciliation.requestIds.filter((value) => typeof value === 'string')
+        : [];
+    return {
+        pendingRequestIds,
+        requestIds,
+        ...('updatedAt' in reconciliation && typeof reconciliation.updatedAt === 'string'
+            ? { updatedAt: reconciliation.updatedAt }
+            : {}),
+    };
+}
+function reconciliationState(state, options) {
+    const current = state && typeof state === 'object' ? state : {};
+    const reconciliation = (() => {
+        const value = current['reconciliation'];
+        if (value && typeof value === 'object')
+            return value;
+        return {};
+    })();
+    return {
+        ...current,
+        reconciliation: {
+            ...reconciliation,
+            pendingRequestIds: options.pendingRequestIds,
+            requestIds: options.requests.highWaterRequestIds,
+            ...(options.requests.highWaterUpdatedAt
+                ? { updatedAt: options.requests.highWaterUpdatedAt }
+                : {}),
+            ...(options.webhookTiming ? { webhookTiming: options.webhookTiming } : {}),
+        },
+    };
+}
+async function observeProviderDelivery(options, verified) {
+    const [entry] = verified;
+    if (!entry ||
+        verified.length !== 1 ||
+        options.address.deliveryStrategy !== 'provider' ||
+        options.address.providerOutputToken.tokenKey !==
+            options.address.snapshot.destinationToken.tokenKey ||
+        (options.request.status === 'success' &&
+            options.request.destinationTransactionHashes.length > 0) ||
+        !options.provider ||
+        !Provider.canObserveDepositAddressRequest(options.provider))
+        return undefined;
+    const result = await options.provider
+        .observeDepositAddressRequest({
+        address: options.address.address,
+        destinationChain: options.address.snapshot.destinationChain,
+        destinationToken: options.address.providerOutputToken,
+        providerState: entry.deposit.providerState ?? undefined,
+        recipient: options.address.recipient,
+        refundAddress: options.address.refundAddress,
+        request: options.request,
+        source: entry.source,
+        sourceChain: options.address.snapshot.sourceChain,
+        sourceToken: options.address.snapshot.sourceToken,
+    }, options.signal ?? new AbortController().signal)
+        .catch((cause) => {
+        if (options.signal?.aborted)
+            throw cause;
+        return undefined;
+    });
+    options.metrics?.count('funding_deposit_delivery_observation_count', 1, {
+        outcome: result?.type ?? 'failed',
+        provider: options.address.providerId,
+    });
+    return result;
+}
+/** Reconciles one provider request against verified chain evidence. */
+export async function reconcileRequest(db, options) {
+    const trigger = options.trigger ?? 'poll';
+    const observation = await FundingDepositRequestObservations.get(db, {
+        depositAddressId: options.address.id,
+        providerRequestId: options.request.id,
+    });
+    if (observation)
+        await FundingDeposits.recordRequestObservation(db, {
+            depositAddressId: observation.depositAddressId,
+            ...(observation.pollObservedAt ? { pollObservedAt: observation.pollObservedAt } : {}),
+            providerRequestId: observation.providerRequestId,
+            ...(observation.webhookReceivedAt
+                ? { webhookReceivedAt: observation.webhookReceivedAt }
+                : {}),
+        });
+    let created = 0;
+    let followUp;
+    const observed = [];
+    // Persist provider observations first so transient chain failures do not hide acknowledged deposits.
+    for (const transactionHash of unique(options.request.sourceTransactionHashes)) {
+        const deposits = await FundingDeposits.withSourceTransaction(db, {
+            depositAddressId: options.address.id,
+            fn: async (tx) => {
+                let records = await FundingDeposits.listByProviderObservation(tx, {
+                    depositAddressId: options.address.id,
+                    providerRequestId: options.request.id,
+                    sourceTransactionHash: transactionHash,
+                });
+                if (records.length === 0)
+                    records = await FundingDeposits.listBySourceTransaction(tx, {
+                        depositAddressId: options.address.id,
+                        sourceTransactionHash: transactionHash,
+                    });
+                if (records.length > 0)
+                    return records;
+                created += 1;
+                return [
+                    await Deposit.create(tx, {
+                        detectionTrigger: trigger,
+                        now: new Date(options.request.createdAt),
+                        ...(observation?.pollObservedAt ? { pollObservedAt: observation.pollObservedAt } : {}),
+                        providerRequestId: options.request.id,
+                        snapshot: {
+                            depositAddressId: options.address.id,
+                            destinationChain: options.address.snapshot.destinationChain,
+                            destinationToken: options.address.snapshot.destinationToken,
+                            provider: options.address.snapshot.provider,
+                            recipient: options.address.recipient,
+                            refundAddress: options.address.refundAddress,
+                            sourceChain: options.address.snapshot.sourceChain,
+                            sourceToken: options.address.snapshot.sourceToken,
+                            sourceTransactionHashes: [transactionHash],
+                        },
+                        sourceTransactionHash: transactionHash,
+                        ...(observation?.webhookReceivedAt
+                            ? { webhookReceivedAt: observation.webhookReceivedAt }
+                            : {}),
+                    }),
+                ];
+            },
+            sourceTransactionHash: transactionHash,
+        });
+        observed.push({ deposits, transactionHash, transfers: [] });
+    }
+    const sources = await Promise.all(observed.map(async (source) => ({
+        ...source,
+        transfers: await options.verifyTransfers({
+            chain: options.address.snapshot.sourceChain,
+            recipient: options.address.address,
+            token: options.address.snapshot.sourceToken,
+            transactionHash: source.transactionHash,
+        }),
+    })));
+    const sourceEvidenceComplete = sources.length > 0 && sources.every((source) => source.transfers.length > 0);
+    let terminal = sourceEvidenceComplete;
+    const updatedIds = new Set();
+    const verified = [];
+    for (const source of sources) {
+        const transfers = [...source.transfers].sort((left, right) => left.transferIndex - right.transferIndex);
+        for (const [providerTransferIndex, transfer] of transfers.entries()) {
+            const required = destinationBaseUnits(BigInt(transfer.amount), options.address.snapshot.sourceToken.decimals, options.address.snapshot.destinationToken.decimals);
+            const sourceAmount = Value.tokenAmount({
+                baseUnits: transfer.amount,
+                currency: options.address.snapshot.sourceToken.currency,
+                decimals: options.address.snapshot.sourceToken.decimals,
+            });
+            const destinationAmountRequired = Value.tokenAmount({
+                baseUnits: required,
+                currency: options.address.snapshot.destinationToken.currency,
+                decimals: options.address.snapshot.destinationToken.decimals,
+            });
+            // Bind the placeholder to transfers in deterministic log order when one transaction contains several deposits.
+            let deposit = source.deposits.find((record) => record.providerRequestId === null
+                ? record.sourceTransferIndex === transfer.transferIndex
+                : record.providerTransferIndex === providerTransferIndex);
+            if (!deposit) {
+                deposit = await Deposit.create(db, {
+                    detectionTrigger: trigger,
+                    now: new Date(options.request.createdAt),
+                    ...(observation?.pollObservedAt ? { pollObservedAt: observation.pollObservedAt } : {}),
+                    providerRequestId: options.request.id,
+                    providerTransferIndex,
+                    snapshot: {
+                        depositAddressId: options.address.id,
+                        ...(options.address.snapshot.subsidize ? { destinationAmountRequired } : {}),
+                        destinationChain: options.address.snapshot.destinationChain,
+                        destinationToken: options.address.snapshot.destinationToken,
+                        provider: options.address.snapshot.provider,
+                        recipient: options.address.recipient,
+                        refundAddress: options.address.refundAddress,
+                        ...(transfer.sender ? { sender: transfer.sender } : {}),
+                        sourceAmount,
+                        sourceChain: options.address.snapshot.sourceChain,
+                        sourceToken: options.address.snapshot.sourceToken,
+                        sourceTransactionHashes: [transfer.transactionHash],
+                    },
+                    sourceTransactionHash: transfer.transactionHash,
+                    sourceTransferIndex: transfer.transferIndex,
+                    ...(observation?.webhookReceivedAt
+                        ? { webhookReceivedAt: observation.webhookReceivedAt }
+                        : {}),
+                });
+                source.deposits.push(deposit);
+                created += 1;
+            }
+            if (!Deposit.isTerminal(deposit.status)) {
+                const result = await Deposit.transition(db, {
+                    expectedVersion: deposit.version,
+                    id: deposit.id,
+                    providerRequestId: options.request.id,
+                    providerRequestIds: unique([...deposit.providerRequestIds, options.request.id]),
+                    providerTransferIndex,
+                    snapshot: {
+                        ...deposit.snapshot,
+                        ...(options.address.snapshot.subsidize ? { destinationAmountRequired } : {}),
+                        ...(transfer.sender ? { sender: transfer.sender } : {}),
+                        sourceAmount,
+                    },
+                    sourceTransferIndex: transfer.transferIndex,
+                    status: deposit.status === 'detected' ? 'bridging' : deposit.status,
+                });
+                if (result.type === 'applied') {
+                    deposit = result.record;
+                    updatedIds.add(deposit.id);
+                }
+            }
+            verified.push({ deposit, required, source: transfer, sourceAmount: BigInt(transfer.amount) });
+        }
+    }
+    if (verified.length === 0)
+        return { created, terminal: false, updated: updatedIds.size };
+    if (!sourceEvidenceComplete)
+        return { created, terminal: false, updated: updatedIds.size };
+    const deliveryObservation = await observeProviderDelivery(options, verified);
+    if (deliveryObservation?.type === 'pending')
+        followUp = 'delivery';
+    const destinationTransactionHashes = unique([
+        ...options.request.destinationTransactionHashes,
+        ...(deliveryObservation?.type === 'verified'
+            ? deliveryObservation.destinationTransactionHashes
+            : []),
+    ]);
+    const destinationEvidence = await Promise.all(destinationTransactionHashes.map((transactionHash) => options.verifyTransfers({
+        chain: options.address.snapshot.destinationChain,
+        recipient: options.address.recipient,
+        token: options.address.providerOutputToken,
+        transactionHash,
+    })));
+    const destinationTransfers = destinationEvidence.flat();
+    const providerEvidenceComplete = (options.request.status === 'success' || deliveryObservation?.type === 'verified') &&
+        destinationEvidence.length > 0 &&
+        destinationEvidence.every((transfers) => transfers.length > 0);
+    const providerOutput = destinationTransfers.reduce((total, transfer) => total + BigInt(transfer.amount), 0n);
+    const totalRequired = verified.reduce((total, entry) => total + entry.required, 0n);
+    let allocated = 0n;
+    let cumulativeRequired = 0n;
+    for (const entry of verified) {
+        const { required, sourceAmount } = entry;
+        cumulativeRequired += required;
+        const nextAllocated = totalRequired === 0n ? 0n : (providerOutput * cumulativeRequired) / totalRequired;
+        const delivered = nextAllocated - allocated;
+        allocated = nextAllocated;
+        const { deposit } = entry;
+        if (Deposit.isTerminal(deposit.status))
+            continue;
+        const settlement = await reconcileSubsidy({
+            address: options.address,
+            delivered,
+            deposit,
+            providerEvidenceComplete,
+            required,
+            sourceAmount,
+            subsidies: options.subsidies,
+            verifyTransfers: options.verifyTransfers,
+        });
+        if (settlement.outcome)
+            options.metrics?.count('funding_deposit_subsidy_count', 1, {
+                outcome: settlement.outcome,
+                provider: options.address.providerId,
+            });
+        if (settlement.status === 'bridging' || settlement.status === 'settling')
+            terminal = false;
+        if (settlement.status === 'settling')
+            followUp = 'settlement';
+        const destinationAmount = Value.tokenAmount({
+            baseUnits: delivered + settlement.delivered,
+            currency: options.address.snapshot.destinationToken.currency,
+            decimals: options.address.snapshot.destinationToken.decimals,
+        });
+        const result = await Deposit.transition(db, {
+            expectedVersion: deposit.version,
+            id: deposit.id,
+            ...(delivered > 0n
+                ? {
+                    providerOutputAmount: Value.tokenAmount({
+                        baseUnits: delivered,
+                        currency: options.address.providerOutputToken.currency,
+                        decimals: options.address.providerOutputToken.decimals,
+                    }),
+                }
+                : {}),
+            providerRequestIds: unique([...deposit.providerRequestIds, options.request.id]),
+            ...(deliveryObservation?.providerState
+                ? {
+                    providerState: {
+                        ...deposit.providerState,
+                        ...deliveryObservation.providerState,
+                    },
+                }
+                : {}),
+            providerTransactionHashes: unique([
+                ...deposit.providerTransactionHashes,
+                ...options.request.destinationTransactionHashes,
+                ...(deliveryObservation?.providerTransactionHashes ?? []),
+            ]),
+            ...(settlement.settlementTransaction
+                ? { settlementTransaction: settlement.settlementTransaction }
+                : {}),
+            ...(settlement.settlementTransactionHash
+                ? { settlementTransactionHash: settlement.settlementTransactionHash }
+                : {}),
+            snapshot: {
+                ...deposit.snapshot,
+                ...(delivered + settlement.delivered > 0n ? { destinationAmount } : {}),
+                ...(settlement.status === 'completed' && !options.address.snapshot.subsidize
+                    ? { destinationAmountRequired: destinationAmount }
+                    : {}),
+                destinationTransactionHashes: unique([
+                    ...(deposit.snapshot.destinationTransactionHashes ?? []),
+                    ...destinationTransfers.map((evidence) => evidence.transactionHash),
+                    ...settlement.destinationTransactionHashes,
+                ]),
+            },
+            status: settlement.status,
+            ...(settlement.statusReason ? { statusReason: settlement.statusReason } : {}),
+            ...(settlement.subsidyAmount ? { subsidyAmount: settlement.subsidyAmount } : {}),
+            ...(settlement.tempoGasPaid ? { tempoGasPaid: settlement.tempoGasPaid } : {}),
+        });
+        if (result.type === 'applied') {
+            updatedIds.add(deposit.id);
+            if (settlement.broadcast && options.subsidies) {
+                await options.subsidies.broadcast(settlement.broadcast).catch((cause) => {
+                    options.metrics?.count('funding_deposit_subsidy_count', 1, {
+                        outcome: 'broadcast_failed',
+                        provider: options.address.providerId,
+                    });
+                    throw cause;
+                });
+                options.metrics?.count('funding_deposit_subsidy_count', 1, {
+                    outcome: 'broadcast',
+                    provider: options.address.providerId,
+                });
+            }
+        }
+    }
+    return { created, ...(followUp ? { followUp } : {}), terminal, updated: updatedIds.size };
+}
+async function reconcileSubsidy(options) {
+    const empty = { delivered: 0n, destinationTransactionHashes: [] };
+    if (options.required === 0n)
+        return {
+            ...empty,
+            status: 'action-required',
+            statusReason: {
+                code: 'source_amount_not_supported',
+                message: 'The source amount is smaller than one destination-token base unit.',
+            },
+        };
+    const deficit = options.required > options.delivered ? options.required - options.delivered : 0n;
+    const subsidyAmount = options.deposit.subsidyAmount ??
+        Value.tokenAmount({
+            baseUnits: deficit,
+            currency: options.address.snapshot.destinationToken.currency,
+            decimals: options.address.snapshot.destinationToken.decimals,
+        });
+    if (options.deposit.settlementTransaction && options.deposit.settlementTransactionHash) {
+        if (!options.subsidies)
+            return {
+                ...empty,
+                outcome: 'unavailable',
+                status: 'action-required',
+                statusReason: {
+                    code: 'subsidy_failed',
+                    message: 'Tempo subsidy settlement is unavailable.',
+                },
+                subsidyAmount,
+            };
+        const hash = options.deposit.settlementTransactionHash;
+        const status = await options.subsidies.status({ hash });
+        if (status.type === 'reverted')
+            return {
+                ...empty,
+                outcome: 'reverted',
+                status: 'action-required',
+                statusReason: {
+                    code: 'subsidy_failed',
+                    message: 'Tempo could not deliver the required subsidy.',
+                },
+                subsidyAmount,
+                tempoGasPaid: status.tempoGasPaid,
+            };
+        if (status.type === 'pending')
+            return {
+                ...empty,
+                broadcast: {
+                    hash,
+                    transaction: options.deposit.settlementTransaction,
+                },
+                outcome: 'pending',
+                status: 'settling',
+                subsidyAmount,
+            };
+        const transfers = await options.verifyTransfers({
+            chain: options.address.snapshot.destinationChain,
+            recipient: options.address.recipient,
+            token: options.address.snapshot.destinationToken,
+            transactionHash: hash,
+        });
+        const delivered = transfers.reduce((total, transfer) => total + BigInt(transfer.amount), 0n);
+        return {
+            delivered,
+            destinationTransactionHashes: transfers.map((transfer) => transfer.transactionHash),
+            outcome: options.delivered + delivered >= options.required ? 'completed' : 'underfilled',
+            status: options.delivered + delivered >= options.required ? 'completed' : 'settling',
+            subsidyAmount,
+            tempoGasPaid: status.tempoGasPaid,
+        };
+    }
+    if (options.delivered >= options.required)
+        return { ...empty, status: 'completed' };
+    if (!options.address.snapshot.subsidize) {
+        if (!options.providerEvidenceComplete)
+            return { ...empty, status: 'bridging' };
+        if (options.delivered > 0n)
+            return { ...empty, status: 'completed' };
+        return {
+            ...empty,
+            status: 'action-required',
+            statusReason: {
+                code: 'delivery_failed',
+                message: 'The provider completed without delivering destination funds.',
+            },
+        };
+    }
+    if (!options.providerEvidenceComplete)
+        return { ...empty, status: 'bridging' };
+    if (!options.subsidies)
+        return {
+            ...empty,
+            outcome: 'unavailable',
+            status: 'action-required',
+            statusReason: {
+                code: 'subsidy_failed',
+                message: 'Tempo subsidy settlement is unavailable.',
+            },
+        };
+    if (!Subsidy.supports(options.subsidies.policy, {
+        amount: options.sourceAmount.toString(),
+        destinationToken: options.address.snapshot.destinationToken,
+        sourceToken: options.address.snapshot.sourceToken,
+    }))
+        return {
+            ...empty,
+            outcome: 'unsupported',
+            status: 'action-required',
+            statusReason: {
+                code: 'source_amount_not_supported',
+                message: 'The source amount is outside the subsidized deposit limit.',
+            },
+        };
+    const prepared = await options.subsidies
+        .prepare({
+        amount: deficit,
+        depositId: options.deposit.id,
+        recipient: options.address.recipient,
+        token: options.address.snapshot.destinationToken.address,
+    })
+        .catch((cause) => {
+        if (cause instanceof Subsidy.BalanceUnavailableError)
+            return undefined;
+        if (cause instanceof Subsidy.LiquidityUnavailableError)
+            return null;
+        throw cause;
+    });
+    if (prepared === null)
+        return {
+            ...empty,
+            outcome: 'liquidity_unavailable',
+            status: 'settling',
+            subsidyAmount,
+        };
+    if (!prepared)
+        return {
+            ...empty,
+            outcome: 'balance_unavailable',
+            status: 'action-required',
+            statusReason: {
+                code: 'subsidy_balance_unavailable',
+                message: 'Tempo lacks enough pathUSD for the required subsidy.',
+            },
+            subsidyAmount,
+        };
+    return {
+        ...empty,
+        broadcast: prepared,
+        outcome: 'prepared',
+        settlementTransaction: prepared.transaction,
+        settlementTransactionHash: prepared.hash,
+        status: 'settling',
+        subsidyAmount,
+    };
+}
+function destinationBaseUnits(amount, sourceDecimals, destinationDecimals) {
+    if (destinationDecimals >= sourceDecimals)
+        return amount * 10n ** BigInt(destinationDecimals - sourceDecimals);
+    const divisor = 10n ** BigInt(sourceDecimals - destinationDecimals);
+    // Destination tokens cannot represent finer source precision, so retain only
+    // the amount expressible in destination base units.
+    return amount / divisor;
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function nextFollowUp(message, kind) {
+    const attempt = message.followUp?.kind === kind ? message.followUp.attempt + 1 : 0;
+    if (attempt >= maximumFollowUpAttempts)
+        return undefined;
+    return { delaySeconds: followUpDelaySeconds[kind], state: { attempt, kind } };
+}
+function recordWebhookLatency(metrics, options) {
+    if (!metrics)
+        return;
+    const completedAt = options.completedAt.getTime();
+    const enqueuedAt = Date.parse(options.timing.enqueuedAt);
+    const providerUpdatedAt = Date.parse(options.timing.providerUpdatedAt);
+    const receivedAt = Date.parse(options.timing.receivedAt);
+    const sentAt = Date.parse(options.timing.sentAt);
+    const segments = [
+        { from: providerUpdatedAt, segment: 'provider_to_sent', to: sentAt },
+        { from: sentAt, segment: 'sent_to_received', to: receivedAt },
+        { from: receivedAt, segment: 'received_to_enqueued', to: enqueuedAt },
+        { from: enqueuedAt, segment: 'enqueued_to_reconciled', to: completedAt },
+        { from: providerUpdatedAt, segment: 'provider_to_reconciled', to: completedAt },
+    ];
+    for (const segment of segments)
+        metrics.histogram('funding_deposit_webhook_latency_ms', Math.max(0, segment.to - segment.from), {
+            provider: options.providerId,
+            segment: segment.segment,
+            status: options.timing.providerStatus,
+        });
+}
+/** Provider pagination exceeded the bounded reconciliation limit. */
+export class PaginationLimitError extends Error {
+    name = 'Funding.Reconciliation.PaginationLimitError';
+}
+/** The reconciliation lease was claimed by another worker. */
+export class StaleLeaseError extends Error {
+    name = 'Funding.Reconciliation.StaleLeaseError';
+}
+//# sourceMappingURL=Reconciliation.js.map