tapimo 0.9.0 → 0.10.0

package/src/internal/funding/Reconciliation.ts

@@ -21,6 +21,8 @@ const followUpDelaySeconds = { delivery: 1, provider: 5, settlement: 2 } as cons
 >
 const maximumPages = 100
 const maximumFollowUpAttempts = 6
+const providerFailureStatuses = ['failure'] as const
+const providerRefundStatuses = ['refund', 'refunded'] as const
 
 /** Verified token transfer returned by an authoritative chain reader. */
 export type TransferEvidence = {
@@ -866,6 +868,16 @@ export async function reconcileRequest(
   }
   if (verified.length === 0) return { created, terminal: false, updated: updatedIds.size }
   if (!sourceEvidenceComplete) return { created, terminal: false, updated: updatedIds.size }
+  const recovery = await reconcileProviderRecovery(db, { ...options, verified })
+  if (recovery) {
+    for (const id of recovery.updatedIds) updatedIds.add(id)
+    return {
+      created,
+      ...(recovery.followUp ? { followUp: recovery.followUp } : {}),
+      terminal: recovery.terminal,
+      updated: updatedIds.size,
+    }
+  }
   const delivery = await reconcileDelivery(db, { ...options, verified })
   for (const id of delivery.updatedIds) updatedIds.add(id)
   return {
@@ -910,6 +922,130 @@ export declare namespace reconcileRequest {
   }
 }
 
+async function reconcileProviderRecovery(db: Db.Db, options: ReconcileDeliveryOptions) {
+  const failed = (providerFailureStatuses as readonly string[]).includes(
+    options.request?.status ?? '',
+  )
+  const refunded = (providerRefundStatuses as readonly string[]).includes(
+    options.request?.status ?? '',
+  )
+  if (!refunded && !failed) return undefined
+  if (failed) {
+    const destinationEvidence = await Promise.all(
+      unique(options.request?.destinationTransactionHashes ?? []).map((transactionHash) =>
+        options.verifyTransfers({
+          chain: options.address.snapshot.destinationChain,
+          recipient: options.address.recipient,
+          token: options.address.providerOutputToken,
+          transactionHash,
+        }),
+      ),
+    )
+    if (destinationEvidence.some((transfers) => transfers.length > 0)) return undefined
+  }
+
+  const updatedIds = new Set<string>()
+  if (options.verified.every((entry) => Deposit.isTerminal(entry.deposit.status)))
+    return { terminal: true, updatedIds }
+
+  // Relay auto-refunds may include an internal settlement transaction; only matching source-token transfers become public evidence.
+  const providerRefundTransactionHashes = unique(options.request?.refundTransactionHashes ?? [])
+  const refundEvidence = await Promise.all(
+    providerRefundTransactionHashes.map((transactionHash) =>
+      options.verifyTransfers({
+        chain: options.address.snapshot.sourceChain,
+        recipient: options.address.refundAddress,
+        token: options.address.snapshot.sourceToken,
+        transactionHash,
+      }),
+    ),
+  )
+  const refundTransfers = refundEvidence.flat()
+  const refundOutput = refundTransfers.reduce(
+    (total, transfer) => total + BigInt(transfer.amount),
+    0n,
+  )
+  const refundTransactionHashes = unique(
+    refundTransfers.map((transfer) => transfer.transactionHash),
+  )
+  // Relay can include internal transactions, so its reported amount proves when all matching refund transfers are visible.
+  const expectedRefundOutput = options.request?.refundAmountExpected
+    ? BigInt(options.request.refundAmountExpected)
+    : undefined
+  const refundEvidenceComplete = (() => {
+    if (refundOutput === 0n) return false
+    if (expectedRefundOutput !== undefined) return refundOutput === expectedRefundOutput
+    return refundEvidence.length > 0 && refundEvidence.every((transfers) => transfers.length > 0)
+  })()
+  const totalSource = options.verified.reduce((total, entry) => total + entry.sourceAmount, 0n)
+  let allocated = 0n
+  let cumulativeSource = 0n
+  let terminal = refundEvidenceComplete
+
+  // Include terminal rows in proportional allocation so retries preserve the original split without reallocating their verified refunds.
+  for (const entry of options.verified) {
+    cumulativeSource += entry.sourceAmount
+    const nextAllocated = totalSource === 0n ? 0n : (refundOutput * cumulativeSource) / totalSource
+    const amount = nextAllocated - allocated
+    allocated = nextAllocated
+    if (Deposit.isTerminal(entry.deposit.status)) continue
+    let deposit = entry.deposit
+    if (deposit.status !== 'refunding') {
+      const result = await Deposit.transition(db, {
+        expectedVersion: deposit.version,
+        id: deposit.id,
+        providerTransactionHashes: unique([
+          ...deposit.providerTransactionHashes,
+          ...providerRefundTransactionHashes,
+        ]),
+        status: 'refunding',
+      })
+      if (result.type === 'applied') {
+        deposit = result.record
+        updatedIds.add(deposit.id)
+      } else if (result.type === 'stale') deposit = result.current
+    }
+    if (!refundEvidenceComplete) continue
+    if (Deposit.isTerminal(deposit.status)) continue
+    if (deposit.status !== 'refunding') {
+      terminal = false
+      continue
+    }
+    const result = await Deposit.transition(db, {
+      expectedVersion: deposit.version,
+      id: deposit.id,
+      snapshot: {
+        ...deposit.snapshot,
+        refundAmount: Value.tokenAmount({
+          baseUnits: amount,
+          currency: options.address.snapshot.sourceToken.currency,
+          decimals: options.address.snapshot.sourceToken.decimals,
+        }),
+        refundTransactionHashes,
+      },
+      status: 'refunded',
+    })
+    if (result.type === 'applied') updatedIds.add(deposit.id)
+    else if (result.type !== 'stale' || !Deposit.isTerminal(result.current.status)) terminal = false
+  }
+
+  const outcome = (() => {
+    if (refundEvidenceComplete) return 'verified'
+    // Relay failure can be followed by an automatic refund; durable exhaustion owns escalation to action-required.
+    if (failed) return 'provider_failed'
+    return 'pending'
+  })()
+  options.metrics?.count('funding_deposit_refund_count', 1, {
+    outcome,
+    provider: options.address.providerId,
+  })
+  return {
+    ...(!refundEvidenceComplete ? { followUp: 'delivery' as const } : {}),
+    terminal,
+    updatedIds,
+  }
+}
+
 async function reconcileDelivery(db: Db.Db, options: ReconcileDeliveryOptions) {
   let followUp: reconcileRequest.ReturnType['followUp']
   let terminal = true

package/src/internal/funding/SourceObservation.test.ts

@@ -188,6 +188,7 @@ describe('observe', () => {
           createdAt: '2026-01-01T00:00:02.000Z',
           destinationTransactionHashes: [],
           id: 'relay-source-request',
+          refundTransactionHashes: [],
           sourceTransactionHashes: [sourceTransactionHash],
           status: 'pending',
           updatedAt: '2026-01-01T00:00:03.000Z',

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

@@ -151,11 +151,8 @@ describe.skipIf(!apiKey)('relay.prepareTransfer (live)', () => {
     expect(result.correlation.requestId).toMatch(/^0x[0-9a-f]{64}$/)
     expect(result.correlation.checkEndpoint).toContain('/intents/status/v3')
     expect(BigInt(result.destinationAmount) > 0n).toBe(true)
+    expect(BigInt(result.destinationAmountMin) > 0n).toBe(true)
     expect(BigInt(result.destinationAmountMin) <= BigInt(result.destinationAmount)).toBe(true)
-    // The forwarded slippage bound holds on the quoted minimum.
-    expect(
-      BigInt(result.destinationAmountMin) >= (BigInt(result.destinationAmount) * 9_700n) / 10_000n,
-    ).toBe(true)
     // Relay returns no quote validity window; the fan-out applies the default.
     expect(result.expiresAt).toBeUndefined()
     expect(Number.isNaN(Date.parse(result.sampledAt))).toBe(false)

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

@@ -17,6 +17,7 @@ const defaultBaseUrl = 'https://api.relay.link'
 const defaultFetch: FundingProvider.Fetch = (input, init) => globalThis.fetch(input, init)
 const deliveryBackfillBlocks = 256n
 const relayChainsCacheTtlMs = 60_000
+const relayRefundStatuses = ['refund', 'refunded'] as const
 const sourceSweepForwardBlocks = 256n
 const depositErc20FullAllowance = AbiFunction.from(
   'function depositErc20(address depositor,address token,bytes32 id)',
@@ -46,6 +47,7 @@ const webhookStatuses = [
   'fallback',
   'pending',
   'refund',
+  'refunded',
   'submitted',
   'success',
   'waiting',
@@ -196,6 +198,13 @@ namespace schema {
           ),
         ),
         id: z.string().check(z.minLength(1)),
+        refundCurrencyData: z.optional(
+          z.nullable(
+            z.object({
+              amount: z.string().check(z.regex(/^\d+$/)),
+            }),
+          ),
+        ),
         protocol: z.optional(
           z.nullable(
             z.object({
@@ -481,6 +490,8 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
       return {
         ...(parsed.continuation ? { continuation: parsed.continuation } : {}),
         requests: parsed.requests.map((request) => {
+          const outputTransactionHashes = request.data?.outTxs?.map((tx) => tx.txHash) ?? []
+          const refunded = (relayRefundStatuses as readonly string[]).includes(request.status)
           const correlation = (() => {
             const { protocol } = request
             if (!protocol) return undefined
@@ -499,9 +510,13 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
           })()
           return {
             createdAt: new Date(request.createdAt).toISOString(),
-            destinationTransactionHashes: request.data?.outTxs?.map((tx) => tx.txHash) ?? [],
+            destinationTransactionHashes: refunded ? [] : outputTransactionHashes,
             id: request.id,
             ...(correlation ? { providerState: correlation } : {}),
+            ...(refunded && request.refundCurrencyData
+              ? { refundAmountExpected: request.refundCurrencyData.amount }
+              : {}),
+            refundTransactionHashes: refunded ? outputTransactionHashes : [],
             sourceTransactionHashes: request.depositAddress?.depositTxHash
               ? [request.depositAddress.depositTxHash]
               : [],