tapimo 0.9.0 → 0.10.0

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

@@ -475,6 +475,7 @@ describe('createTracker', () => {
           createdAt: '2026-01-06T00:01:00.000Z',
           destinationTransactionHashes: [destinationTransactionHash],
           id: 'unsubsidized-request',
+          refundTransactionHashes: [],
           sourceTransactionHashes: [sourceTransactionHash],
           status: 'success',
           updatedAt: '2026-01-06T00:02:00.000Z',
@@ -626,6 +627,1244 @@ describe('createTracker', () => {
     }
   })
 
+  test('verifies Relay refunds on the source chain before completing recovery', async () => {
+    const route = TestFunding.transferSnapshot()
+    const depositAddress = `0x${'48'.repeat(20)}`
+    const firstRefundTransactionHash = `0x${'ce'.repeat(32)}`
+    const refundAddress = `0x${'49'.repeat(20)}`
+    const secondRefundTransactionHash = `0x${'cd'.repeat(32)}`
+    const settlementTransactionHash = `0x${'cf'.repeat(32)}`
+    const sourceTransactionHash = `0x${'ac'.repeat(32)}`
+    const address = await DepositAddress.create(db, {
+      apiKeyId: 'key_refund_reconciliation',
+      deliveryStrategy: 'provider',
+      environment: 'production',
+      now: new Date('2026-01-07T00:00:00.000Z'),
+      orgId: 'org_refund_reconciliation',
+      providerOutputToken: route.destinationToken,
+      snapshot: {
+        address: depositAddress,
+        destinationChain: route.destinationChain,
+        destinationToken: route.destinationToken,
+        provider: { id: 'relay', name: 'Relay' },
+        recipient: route.recipient,
+        refundAddress,
+        sourceChain: route.sourceChain,
+        sourceToken: route.sourceToken,
+        subsidize: false,
+      },
+    })
+    const counts: Parameters<Metrics.Metrics['count']>[] = []
+    const metrics = Metrics.from({
+      count(...parameters) {
+        counts.push(parameters)
+      },
+      flush() {},
+      gauge() {},
+      histogram() {},
+    })
+    let secondRefundVisible = false
+    const server = await TestRelay.createServer(async (request, response) => {
+      response.writeHead(200, { 'content-type': 'application/json' })
+      if (request.method === 'GET') {
+        response.end(
+          JSON.stringify({
+            requests: [
+              {
+                createdAt: '2026-01-07T00:01:00.000Z',
+                data: {
+                  outTxs: [
+                    { txHash: firstRefundTransactionHash },
+                    { txHash: firstRefundTransactionHash },
+                    { txHash: secondRefundTransactionHash },
+                    { txHash: settlementTransactionHash },
+                  ],
+                },
+                depositAddress: { depositTxHash: sourceTransactionHash },
+                id: 'relay-refund-request',
+                refundCurrencyData: { amount: '900000' },
+                status: 'refund',
+                updatedAt: '2026-01-07T00:02:00.000Z',
+              },
+            ],
+          }),
+        )
+        return
+      }
+
+      const chunks: Uint8Array[] = []
+      for await (const chunk of request) chunks.push(chunk)
+      const body = JSON.parse(NodeBuffer.Buffer.concat(chunks).toString()) as {
+        id: number
+        method: string
+        params?: readonly string[] | undefined
+      }
+      const hash = body.params?.[0]
+      const result = (() => {
+        if (body.method === 'eth_blockNumber') return '0x100'
+        if (hash === secondRefundTransactionHash && !secondRefundVisible) return null
+        const log = (() => {
+          if (hash === sourceTransactionHash)
+            return transferLog({
+              amount: 1_000_000n,
+              recipient: depositAddress,
+              sender: `0x${'4a'.repeat(20)}`,
+              token: route.sourceToken.address,
+            })
+          if (hash === firstRefundTransactionHash)
+            return transferLog({
+              amount: 400_000n,
+              recipient: refundAddress,
+              sender: `0x${'4b'.repeat(20)}`,
+              token: route.sourceToken.address,
+            })
+          if (hash === secondRefundTransactionHash)
+            return transferLog({
+              amount: 500_000n,
+              recipient: refundAddress,
+              sender: `0x${'4b'.repeat(20)}`,
+              token: route.sourceToken.address,
+            })
+          return transferLog({
+            amount: 100_000n,
+            recipient: `0x${'4c'.repeat(20)}`,
+            sender: `0x${'4b'.repeat(20)}`,
+            token: route.sourceToken.address,
+          })
+        })()
+        return { blockNumber: '0x80', logs: [log], status: '0x1' }
+      })()
+      response.end(JSON.stringify({ id: body.id, jsonrpc: '2.0', result }))
+    })
+
+    try {
+      await FundingCatalog.publish(db, {
+        chainTokens: [],
+        chains: [
+          {
+            aliases: [],
+            id: route.destinationChain.id as Chain.Id,
+            name: route.destinationChain.name,
+            parentChainId: null,
+            rpcUrls: [server.url],
+            slug: 'destination-refund',
+          },
+          {
+            aliases: [],
+            id: route.sourceChain.id as Chain.Id,
+            name: route.sourceChain.name,
+            parentChainId: null,
+            rpcUrls: [server.url],
+            slug: 'source-refund',
+          },
+        ],
+        routes: [],
+        tokens: [],
+      })
+      const provider = Relay.relay({ apiKey: 'relay-api-key', baseUrl: server.url })
+      const request = (
+        await provider.listDepositAddressRequests!(
+          { address: depositAddress },
+          new AbortController().signal,
+        )
+      ).requests[0]
+      if (!request) throw new Error('Expected a Relay refund request.')
+      const verifyTransfers = Evidence.createVerifier({ db })
+      const first = await Reconciliation.reconcileRequest(db, {
+        address,
+        metrics,
+        request,
+        verifyTransfers,
+      })
+      const [firstRecord] = await FundingDeposits.listBySourceTransaction(db, {
+        depositAddressId: address.id,
+        sourceTransactionHash,
+      })
+      secondRefundVisible = true
+      const second = await Reconciliation.reconcileRequest(db, {
+        address,
+        metrics,
+        request,
+        verifyTransfers,
+      })
+      const duplicate = await Reconciliation.reconcileRequest(db, {
+        address,
+        metrics,
+        request,
+        verifyTransfers,
+      })
+      const [record] = await FundingDeposits.listBySourceTransaction(db, {
+        depositAddressId: address.id,
+        sourceTransactionHash,
+      })
+
+      expect({
+        counts,
+        duplicate,
+        first,
+        firstRecord,
+        record,
+        request,
+        second,
+      }).toMatchInlineSnapshot(
+        {
+          firstRecord: {
+            createdAt: expect.any(String),
+            depositAddressId: expect.any(String),
+            id: expect.any(String),
+            snapshot: { depositAddressId: expect.any(String) },
+            updatedAt: expect.any(String),
+          },
+          record: {
+            createdAt: expect.any(String),
+            depositAddressId: expect.any(String),
+            id: expect.any(String),
+            snapshot: { depositAddressId: expect.any(String) },
+            updatedAt: expect.any(String),
+          },
+        },
+        `
+        {
+          "counts": [
+            [
+              "funding_deposit_refund_count",
+              1,
+              {
+                "outcome": "pending",
+                "provider": "relay",
+              },
+            ],
+            [
+              "funding_deposit_refund_count",
+              1,
+              {
+                "outcome": "verified",
+                "provider": "relay",
+              },
+            ],
+          ],
+          "duplicate": {
+            "created": 0,
+            "terminal": true,
+            "updated": 0,
+          },
+          "first": {
+            "created": 1,
+            "followUp": "delivery",
+            "terminal": false,
+            "updated": 1,
+          },
+          "firstRecord": {
+            "createdAt": Any<String>,
+            "depositAddressId": Any<String>,
+            "detectionTrigger": "poll",
+            "environment": "production",
+            "id": Any<String>,
+            "orgId": "org_refund_reconciliation",
+            "pollObservedAt": null,
+            "projectId": null,
+            "providerOutputAmount": null,
+            "providerOutputToken": {
+              "address": "0x20c000000000000000000000b9537d11c60e8b50",
+              "currency": "USD",
+              "decimals": 6,
+              "name": "Bridged USDC (Stargate)",
+              "standard": "TIP-20",
+              "symbol": "USDC.e",
+              "tokenKey": "eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50",
+              "verified": true,
+            },
+            "providerRequestId": "relay-refund-request",
+            "providerRequestIds": [
+              "relay-refund-request",
+            ],
+            "providerState": null,
+            "providerTransactionHashes": [
+              "0xcececececececececececececececececececececececececececececececece",
+              "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
+              "0xcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcf",
+            ],
+            "providerTransferIndex": 0,
+            "retryState": null,
+            "settlementTransaction": null,
+            "settlementTransactionHash": null,
+            "snapshot": {
+              "depositAddressId": Any<String>,
+              "destinationChain": {
+                "addressFormat": "hex",
+                "id": "eip155:4217",
+                "kind": "evm",
+                "name": "Tempo",
+              },
+              "destinationToken": {
+                "address": "0x20c000000000000000000000b9537d11c60e8b50",
+                "currency": "USD",
+                "decimals": 6,
+                "name": "Bridged USDC (Stargate)",
+                "standard": "TIP-20",
+                "symbol": "USDC.e",
+                "tokenKey": "eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50",
+                "verified": true,
+              },
+              "provider": {
+                "id": "relay",
+                "name": "Relay",
+              },
+              "recipient": "0x1111111111111111111111111111111111111111",
+              "refundAddress": "0x4949494949494949494949494949494949494949",
+              "sender": "0x4a4a4a4a4a4a4a4a4a4a4a4a4a4a4a4a4a4a4a4a",
+              "sourceAmount": {
+                "baseUnits": "1000000",
+                "currency": "USD",
+                "decimals": 6,
+                "formatted": "1",
+              },
+              "sourceChain": {
+                "addressFormat": "hex",
+                "id": "eip155:8453",
+                "kind": "evm",
+                "name": "Base",
+              },
+              "sourceToken": {
+                "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                "currency": "USD",
+                "decimals": 6,
+                "name": "USD Coin",
+                "standard": "ERC-20",
+                "symbol": "USDC",
+                "tokenKey": "eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                "verified": true,
+              },
+              "sourceTransactionHashes": [
+                "0xacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacac",
+              ],
+            },
+            "sourceChainId": "eip155:8453",
+            "sourceTransactionHash": "0xacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacac",
+            "sourceTransferIndex": 0,
+            "status": "refunding",
+            "statusReason": null,
+            "subsidyAmount": null,
+            "tempoGasPaid": null,
+            "updatedAt": Any<String>,
+            "version": 3,
+            "webhookReceivedAt": null,
+          },
+          "record": {
+            "createdAt": Any<String>,
+            "depositAddressId": Any<String>,
+            "detectionTrigger": "poll",
+            "environment": "production",
+            "id": Any<String>,
+            "orgId": "org_refund_reconciliation",
+            "pollObservedAt": null,
+            "projectId": null,
+            "providerOutputAmount": null,
+            "providerOutputToken": {
+              "address": "0x20c000000000000000000000b9537d11c60e8b50",
+              "currency": "USD",
+              "decimals": 6,
+              "name": "Bridged USDC (Stargate)",
+              "standard": "TIP-20",
+              "symbol": "USDC.e",
+              "tokenKey": "eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50",
+              "verified": true,
+            },
+            "providerRequestId": "relay-refund-request",
+            "providerRequestIds": [
+              "relay-refund-request",
+            ],
+            "providerState": null,
+            "providerTransactionHashes": [
+              "0xcececececececececececececececececececececececececececececececece",
+              "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
+              "0xcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcf",
+            ],
+            "providerTransferIndex": 0,
+            "retryState": null,
+            "settlementTransaction": null,
+            "settlementTransactionHash": null,
+            "snapshot": {
+              "depositAddressId": Any<String>,
+              "destinationChain": {
+                "addressFormat": "hex",
+                "id": "eip155:4217",
+                "kind": "evm",
+                "name": "Tempo",
+              },
+              "destinationToken": {
+                "address": "0x20c000000000000000000000b9537d11c60e8b50",
+                "currency": "USD",
+                "decimals": 6,
+                "name": "Bridged USDC (Stargate)",
+                "standard": "TIP-20",
+                "symbol": "USDC.e",
+                "tokenKey": "eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50",
+                "verified": true,
+              },
+              "provider": {
+                "id": "relay",
+                "name": "Relay",
+              },
+              "recipient": "0x1111111111111111111111111111111111111111",
+              "refundAddress": "0x4949494949494949494949494949494949494949",
+              "refundAmount": {
+                "baseUnits": "900000",
+                "currency": "USD",
+                "decimals": 6,
+                "formatted": "0.9",
+              },
+              "refundTransactionHashes": [
+                "0xcececececececececececececececececececececececececececececececece",
+                "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
+              ],
+              "sender": "0x4a4a4a4a4a4a4a4a4a4a4a4a4a4a4a4a4a4a4a4a",
+              "sourceAmount": {
+                "baseUnits": "1000000",
+                "currency": "USD",
+                "decimals": 6,
+                "formatted": "1",
+              },
+              "sourceChain": {
+                "addressFormat": "hex",
+                "id": "eip155:8453",
+                "kind": "evm",
+                "name": "Base",
+              },
+              "sourceToken": {
+                "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                "currency": "USD",
+                "decimals": 6,
+                "name": "USD Coin",
+                "standard": "ERC-20",
+                "symbol": "USDC",
+                "tokenKey": "eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                "verified": true,
+              },
+              "sourceTransactionHashes": [
+                "0xacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacac",
+              ],
+            },
+            "sourceChainId": "eip155:8453",
+            "sourceTransactionHash": "0xacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacac",
+            "sourceTransferIndex": 0,
+            "status": "refunded",
+            "statusReason": null,
+            "subsidyAmount": null,
+            "tempoGasPaid": null,
+            "updatedAt": Any<String>,
+            "version": 5,
+            "webhookReceivedAt": null,
+          },
+          "request": {
+            "createdAt": "2026-01-07T00:01:00.000Z",
+            "destinationTransactionHashes": [],
+            "id": "relay-refund-request",
+            "refundAmountExpected": "900000",
+            "refundTransactionHashes": [
+              "0xcececececececececececececececececececececececececececececececece",
+              "0xcececececececececececececececececececececececececececececececece",
+              "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
+              "0xcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcf",
+            ],
+            "sourceTransactionHashes": [
+              "0xacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacac",
+            ],
+            "status": "refund",
+            "updatedAt": "2026-01-07T00:02:00.000Z",
+          },
+          "second": {
+            "created": 0,
+            "terminal": true,
+            "updated": 1,
+          },
+        }
+      `,
+      )
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test('preserves refund allocations when retrying a partially committed request', async () => {
+    const route = TestFunding.transferSnapshot()
+    const depositAddress = `0x${'50'.repeat(20)}`
+    const refundAddress = `0x${'51'.repeat(20)}`
+    const refundTransactionHash = `0x${'d0'.repeat(32)}`
+    const sourceTransactionHash = `0x${'b0'.repeat(32)}`
+    const address = await DepositAddress.create(db, {
+      apiKeyId: 'key_refund_retry',
+      deliveryStrategy: 'provider',
+      environment: 'production',
+      now: new Date('2026-01-09T00:00:00.000Z'),
+      orgId: 'org_refund_retry',
+      providerOutputToken: route.destinationToken,
+      snapshot: {
+        address: depositAddress,
+        destinationChain: route.destinationChain,
+        destinationToken: route.destinationToken,
+        provider: { id: 'relay', name: 'Relay' },
+        recipient: route.recipient,
+        refundAddress,
+        sourceChain: route.sourceChain,
+        sourceToken: route.sourceToken,
+        subsidize: false,
+      },
+    })
+    const first = await Deposit.create(db, {
+      id: 'fdp_refund_retry_0',
+      now: new Date('2026-01-09T00:01:00.000Z'),
+      providerRequestId: 'relay-refund-retry-request',
+      providerTransferIndex: 0,
+      snapshot: {
+        depositAddressId: address.id,
+        destinationChain: route.destinationChain,
+        destinationToken: route.destinationToken,
+        provider: { id: 'relay', name: 'Relay' },
+        recipient: route.recipient,
+        refundAddress,
+        sourceAmount: {
+          baseUnits: '1000000',
+          currency: route.sourceToken.currency,
+          decimals: route.sourceToken.decimals,
+          formatted: '1',
+        },
+        sourceChain: route.sourceChain,
+        sourceToken: route.sourceToken,
+        sourceTransactionHashes: [sourceTransactionHash],
+      },
+      sourceTransactionHash,
+      sourceTransferIndex: 0,
+    })
+    await Deposit.create(db, {
+      id: 'fdp_refund_retry_1',
+      now: new Date('2026-01-09T00:01:01.000Z'),
+      providerRequestId: 'relay-refund-retry-request',
+      providerTransferIndex: 1,
+      snapshot: {
+        depositAddressId: address.id,
+        destinationChain: route.destinationChain,
+        destinationToken: route.destinationToken,
+        provider: { id: 'relay', name: 'Relay' },
+        recipient: route.recipient,
+        refundAddress,
+        sourceAmount: {
+          baseUnits: '2000000',
+          currency: route.sourceToken.currency,
+          decimals: route.sourceToken.decimals,
+          formatted: '2',
+        },
+        sourceChain: route.sourceChain,
+        sourceToken: route.sourceToken,
+        sourceTransactionHashes: [sourceTransactionHash],
+      },
+      sourceTransactionHash,
+      sourceTransferIndex: 1,
+    })
+    const refunding = await Deposit.transition(db, {
+      expectedVersion: first.version,
+      id: first.id,
+      providerTransactionHashes: [refundTransactionHash],
+      status: 'refunding',
+    })
+    if (refunding.type !== 'applied') throw new Error('Expected the first deposit to refund.')
+    const refunded = await Deposit.transition(db, {
+      expectedVersion: refunding.record.version,
+      id: refunding.record.id,
+      snapshot: {
+        ...refunding.record.snapshot,
+        refundAmount: {
+          baseUnits: '300000',
+          currency: route.sourceToken.currency,
+          decimals: route.sourceToken.decimals,
+          formatted: '0.3',
+        },
+        refundTransactionHashes: [refundTransactionHash],
+      },
+      status: 'refunded',
+    })
+    if (refunded.type !== 'applied') throw new Error('Expected the first deposit to be refunded.')
+
+    const server = await TestRelay.createServer(async (request, response) => {
+      const chunks: Uint8Array[] = []
+      for await (const chunk of request) chunks.push(chunk)
+      const body = JSON.parse(NodeBuffer.Buffer.concat(chunks).toString()) as {
+        id: number
+        method: string
+        params?: readonly string[] | undefined
+      }
+      const hash = body.params?.[0]
+      const result = (() => {
+        if (body.method === 'eth_blockNumber') return '0x100'
+        if (hash === sourceTransactionHash)
+          return {
+            blockNumber: '0x80',
+            logs: [
+              transferLog({
+                amount: 1_000_000n,
+                logIndex: 0,
+                recipient: depositAddress,
+                sender: `0x${'52'.repeat(20)}`,
+                token: route.sourceToken.address,
+              }),
+              transferLog({
+                amount: 2_000_000n,
+                logIndex: 1,
+                recipient: depositAddress,
+                sender: `0x${'53'.repeat(20)}`,
+                token: route.sourceToken.address,
+              }),
+            ],
+            status: '0x1',
+          }
+        return {
+          blockNumber: '0x80',
+          logs: [
+            transferLog({
+              amount: 900_000n,
+              recipient: refundAddress,
+              sender: `0x${'54'.repeat(20)}`,
+              token: route.sourceToken.address,
+            }),
+          ],
+          status: '0x1',
+        }
+      })()
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(JSON.stringify({ id: body.id, jsonrpc: '2.0', result }))
+    })
+
+    try {
+      await FundingCatalog.publish(db, {
+        chainTokens: [],
+        chains: [
+          {
+            aliases: [],
+            id: route.destinationChain.id as Chain.Id,
+            name: route.destinationChain.name,
+            parentChainId: null,
+            rpcUrls: [server.url],
+            slug: 'destination-refund-retry',
+          },
+          {
+            aliases: [],
+            id: route.sourceChain.id as Chain.Id,
+            name: route.sourceChain.name,
+            parentChainId: null,
+            rpcUrls: [server.url],
+            slug: 'source-refund-retry',
+          },
+        ],
+        routes: [],
+        tokens: [],
+      })
+      const result = await Reconciliation.reconcileRequest(db, {
+        address,
+        request: {
+          createdAt: '2026-01-09T00:01:00.000Z',
+          destinationTransactionHashes: [],
+          id: 'relay-refund-retry-request',
+          refundTransactionHashes: [refundTransactionHash],
+          sourceTransactionHashes: [sourceTransactionHash],
+          status: 'refund',
+          updatedAt: '2026-01-09T00:02:00.000Z',
+        },
+        verifyTransfers: Evidence.createVerifier({ db }),
+      })
+      const records = (
+        await FundingDeposits.listBySourceTransaction(db, {
+          depositAddressId: address.id,
+          sourceTransactionHash,
+        })
+      ).sort((left, right) => left.providerTransferIndex - right.providerTransferIndex)
+
+      expect({ records: records.map(Deposit.toPublic), result }).toMatchInlineSnapshot(
+        {
+          records: [
+            { depositAddressId: expect.any(String), updatedAt: expect.any(String) },
+            { depositAddressId: expect.any(String), updatedAt: expect.any(String) },
+          ],
+        },
+        `
+        {
+          "records": [
+            {
+              "createdAt": "2026-01-09T00:01:00.000Z",
+              "depositAddressId": Any<String>,
+              "destinationChain": {
+                "addressFormat": "hex",
+                "id": "eip155:4217",
+                "kind": "evm",
+                "name": "Tempo",
+              },
+              "destinationToken": {
+                "address": "0x20c000000000000000000000b9537d11c60e8b50",
+                "currency": "USD",
+                "decimals": 6,
+                "name": "Bridged USDC (Stargate)",
+                "standard": "TIP-20",
+                "symbol": "USDC.e",
+                "tokenKey": "eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50",
+                "verified": true,
+              },
+              "id": "fdp_refund_retry_0",
+              "provider": {
+                "id": "relay",
+                "name": "Relay",
+              },
+              "recipient": "0x1111111111111111111111111111111111111111",
+              "refundAddress": "0x5151515151515151515151515151515151515151",
+              "refundAmount": {
+                "baseUnits": "300000",
+                "currency": "USD",
+                "decimals": 6,
+                "formatted": "0.3",
+              },
+              "refundTransactionHashes": [
+                "0xd0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0",
+              ],
+              "sourceAmount": {
+                "baseUnits": "1000000",
+                "currency": "USD",
+                "decimals": 6,
+                "formatted": "1",
+              },
+              "sourceChain": {
+                "addressFormat": "hex",
+                "id": "eip155:8453",
+                "kind": "evm",
+                "name": "Base",
+              },
+              "sourceToken": {
+                "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                "currency": "USD",
+                "decimals": 6,
+                "name": "USD Coin",
+                "standard": "ERC-20",
+                "symbol": "USDC",
+                "tokenKey": "eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                "verified": true,
+              },
+              "sourceTransactionHashes": [
+                "0xb0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0",
+              ],
+              "sourceTransferIndex": 0,
+              "status": "refunded",
+              "updatedAt": Any<String>,
+            },
+            {
+              "createdAt": "2026-01-09T00:01:01.000Z",
+              "depositAddressId": Any<String>,
+              "destinationChain": {
+                "addressFormat": "hex",
+                "id": "eip155:4217",
+                "kind": "evm",
+                "name": "Tempo",
+              },
+              "destinationToken": {
+                "address": "0x20c000000000000000000000b9537d11c60e8b50",
+                "currency": "USD",
+                "decimals": 6,
+                "name": "Bridged USDC (Stargate)",
+                "standard": "TIP-20",
+                "symbol": "USDC.e",
+                "tokenKey": "eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50",
+                "verified": true,
+              },
+              "id": "fdp_refund_retry_1",
+              "provider": {
+                "id": "relay",
+                "name": "Relay",
+              },
+              "recipient": "0x1111111111111111111111111111111111111111",
+              "refundAddress": "0x5151515151515151515151515151515151515151",
+              "refundAmount": {
+                "baseUnits": "600000",
+                "currency": "USD",
+                "decimals": 6,
+                "formatted": "0.6",
+              },
+              "refundTransactionHashes": [
+                "0xd0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0",
+              ],
+              "sender": "0x5353535353535353535353535353535353535353",
+              "sourceAmount": {
+                "baseUnits": "2000000",
+                "currency": "USD",
+                "decimals": 6,
+                "formatted": "2",
+              },
+              "sourceChain": {
+                "addressFormat": "hex",
+                "id": "eip155:8453",
+                "kind": "evm",
+                "name": "Base",
+              },
+              "sourceToken": {
+                "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                "currency": "USD",
+                "decimals": 6,
+                "name": "USD Coin",
+                "standard": "ERC-20",
+                "symbol": "USDC",
+                "tokenKey": "eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                "verified": true,
+              },
+              "sourceTransactionHashes": [
+                "0xb0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0",
+              ],
+              "sourceTransferIndex": 1,
+              "status": "refunded",
+              "updatedAt": Any<String>,
+            },
+          ],
+          "result": {
+            "created": 0,
+            "terminal": true,
+            "updated": 1,
+          },
+        }
+      `,
+      )
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test('reconciles destination evidence reported with a Relay failure', async () => {
+    const route = TestFunding.transferSnapshot()
+    const depositAddress = `0x${'56'.repeat(20)}`
+    const destinationTransactionHash = `0x${'d1'.repeat(32)}`
+    const sourceTransactionHash = `0x${'b1'.repeat(32)}`
+    const address = await DepositAddress.create(db, {
+      apiKeyId: 'key_failure_delivery',
+      deliveryStrategy: 'provider',
+      environment: 'production',
+      now: new Date('2026-01-10T00:00:00.000Z'),
+      orgId: 'org_failure_delivery',
+      providerOutputToken: route.destinationToken,
+      snapshot: {
+        address: depositAddress,
+        destinationChain: route.destinationChain,
+        destinationToken: route.destinationToken,
+        provider: { id: 'relay', name: 'Relay' },
+        recipient: route.recipient,
+        refundAddress: `0x${'57'.repeat(20)}`,
+        sourceChain: route.sourceChain,
+        sourceToken: route.sourceToken,
+        subsidize: false,
+      },
+    })
+    const server = await TestRelay.createServer(async (request, response) => {
+      const chunks: Uint8Array[] = []
+      for await (const chunk of request) chunks.push(chunk)
+      const body = JSON.parse(NodeBuffer.Buffer.concat(chunks).toString()) as {
+        id: number
+        method: string
+        params?: readonly string[] | undefined
+      }
+      const hash = body.params?.[0]
+      const result = (() => {
+        if (body.method === 'eth_blockNumber') return '0x100'
+        if (hash === sourceTransactionHash)
+          return {
+            blockNumber: '0x80',
+            logs: [
+              transferLog({
+                amount: 1_000_000n,
+                recipient: depositAddress,
+                sender: `0x${'58'.repeat(20)}`,
+                token: route.sourceToken.address,
+              }),
+            ],
+            status: '0x1',
+          }
+        return {
+          blockNumber: '0x80',
+          logs: [
+            transferLog({
+              amount: 1_000_000n,
+              recipient: route.recipient,
+              sender: `0x${'59'.repeat(20)}`,
+              token: route.destinationToken.address,
+            }),
+          ],
+          status: '0x1',
+        }
+      })()
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(JSON.stringify({ id: body.id, jsonrpc: '2.0', result }))
+    })
+
+    try {
+      await FundingCatalog.publish(db, {
+        chainTokens: [],
+        chains: [
+          {
+            aliases: [],
+            id: route.destinationChain.id as Chain.Id,
+            name: route.destinationChain.name,
+            parentChainId: null,
+            rpcUrls: [server.url],
+            slug: 'destination-failure-delivery',
+          },
+          {
+            aliases: [],
+            id: route.sourceChain.id as Chain.Id,
+            name: route.sourceChain.name,
+            parentChainId: null,
+            rpcUrls: [server.url],
+            slug: 'source-failure-delivery',
+          },
+        ],
+        routes: [],
+        tokens: [],
+      })
+      const result = await Reconciliation.reconcileRequest(db, {
+        address,
+        request: {
+          createdAt: '2026-01-10T00:01:00.000Z',
+          destinationTransactionHashes: [destinationTransactionHash],
+          id: 'relay-failure-delivery-request',
+          refundTransactionHashes: [],
+          sourceTransactionHashes: [sourceTransactionHash],
+          status: 'failure',
+          updatedAt: '2026-01-10T00:02:00.000Z',
+        },
+        verifyTransfers: Evidence.createVerifier({ db }),
+      })
+      const [record] = await FundingDeposits.listBySourceTransaction(db, {
+        depositAddressId: address.id,
+        sourceTransactionHash,
+      })
+      if (!record) throw new Error('Expected a reconciled deposit.')
+
+      expect({ record: Deposit.toPublic(record), result }).toMatchInlineSnapshot(
+        {
+          record: {
+            createdAt: expect.any(String),
+            depositAddressId: expect.any(String),
+            id: expect.any(String),
+            updatedAt: expect.any(String),
+          },
+        },
+        `
+        {
+          "record": {
+            "createdAt": Any<String>,
+            "depositAddressId": Any<String>,
+            "destinationAmount": {
+              "baseUnits": "1000000",
+              "currency": "USD",
+              "decimals": 6,
+              "formatted": "1",
+            },
+            "destinationAmountRequired": {
+              "baseUnits": "1000000",
+              "currency": "USD",
+              "decimals": 6,
+              "formatted": "1",
+            },
+            "destinationChain": {
+              "addressFormat": "hex",
+              "id": "eip155:4217",
+              "kind": "evm",
+              "name": "Tempo",
+            },
+            "destinationToken": {
+              "address": "0x20c000000000000000000000b9537d11c60e8b50",
+              "currency": "USD",
+              "decimals": 6,
+              "name": "Bridged USDC (Stargate)",
+              "standard": "TIP-20",
+              "symbol": "USDC.e",
+              "tokenKey": "eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50",
+              "verified": true,
+            },
+            "destinationTransactionHashes": [
+              "0xd1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1",
+            ],
+            "detectionTrigger": "poll",
+            "id": Any<String>,
+            "provider": {
+              "id": "relay",
+              "name": "Relay",
+            },
+            "recipient": "0x1111111111111111111111111111111111111111",
+            "refundAddress": "0x5757575757575757575757575757575757575757",
+            "sender": "0x5858585858585858585858585858585858585858",
+            "sourceAmount": {
+              "baseUnits": "1000000",
+              "currency": "USD",
+              "decimals": 6,
+              "formatted": "1",
+            },
+            "sourceChain": {
+              "addressFormat": "hex",
+              "id": "eip155:8453",
+              "kind": "evm",
+              "name": "Base",
+            },
+            "sourceToken": {
+              "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+              "currency": "USD",
+              "decimals": 6,
+              "name": "USD Coin",
+              "standard": "ERC-20",
+              "symbol": "USDC",
+              "tokenKey": "eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+              "verified": true,
+            },
+            "sourceTransactionHashes": [
+              "0xb1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1",
+            ],
+            "sourceTransferIndex": 0,
+            "status": "completed",
+            "updatedAt": Any<String>,
+          },
+          "result": {
+            "created": 1,
+            "terminal": true,
+            "updated": 1,
+          },
+        }
+      `,
+      )
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test('keeps Relay failures with unverified destination transactions pending for recovery', async () => {
+    const route = TestFunding.transferSnapshot()
+    const depositAddress = `0x${'4d'.repeat(20)}`
+    const sourceTransactionHash = `0x${'ad'.repeat(32)}`
+    const unrelatedDestinationTransactionHash = `0x${'d2'.repeat(32)}`
+    const address = await DepositAddress.create(db, {
+      apiKeyId: 'key_failed_reconciliation',
+      deliveryStrategy: 'provider',
+      environment: 'production',
+      now: new Date('2026-01-08T00:00:00.000Z'),
+      orgId: 'org_failed_reconciliation',
+      providerOutputToken: route.destinationToken,
+      snapshot: {
+        address: depositAddress,
+        destinationChain: route.destinationChain,
+        destinationToken: route.destinationToken,
+        provider: { id: 'relay', name: 'Relay' },
+        recipient: route.recipient,
+        refundAddress: `0x${'4e'.repeat(20)}`,
+        sourceChain: route.sourceChain,
+        sourceToken: route.sourceToken,
+        subsidize: false,
+      },
+    })
+    const counts: Parameters<Metrics.Metrics['count']>[] = []
+    const metrics = Metrics.from({
+      count(...parameters) {
+        counts.push(parameters)
+      },
+      flush() {},
+      gauge() {},
+      histogram() {},
+    })
+    const server = await TestRelay.createServer(async (request, response) => {
+      const chunks: Uint8Array[] = []
+      for await (const chunk of request) chunks.push(chunk)
+      const body = JSON.parse(NodeBuffer.Buffer.concat(chunks).toString()) as {
+        id: number
+        method: string
+      }
+      const result =
+        body.method === 'eth_blockNumber'
+          ? '0x100'
+          : {
+              blockNumber: '0x80',
+              logs: [
+                transferLog({
+                  amount: 1_000_000n,
+                  recipient: depositAddress,
+                  sender: `0x${'4f'.repeat(20)}`,
+                  token: route.sourceToken.address,
+                }),
+              ],
+              status: '0x1',
+            }
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(JSON.stringify({ id: body.id, jsonrpc: '2.0', result }))
+    })
+
+    try {
+      await FundingCatalog.publish(db, {
+        chainTokens: [],
+        chains: [
+          {
+            aliases: [],
+            id: route.destinationChain.id as Chain.Id,
+            name: route.destinationChain.name,
+            parentChainId: null,
+            rpcUrls: [server.url],
+            slug: 'destination-failed',
+          },
+          {
+            aliases: [],
+            id: route.sourceChain.id as Chain.Id,
+            name: route.sourceChain.name,
+            parentChainId: null,
+            rpcUrls: [server.url],
+            slug: 'source-failed',
+          },
+        ],
+        routes: [],
+        tokens: [],
+      })
+      const result = await Reconciliation.reconcileRequest(db, {
+        address,
+        metrics,
+        request: {
+          createdAt: '2026-01-08T00:01:00.000Z',
+          destinationTransactionHashes: [unrelatedDestinationTransactionHash],
+          id: 'relay-failed-request',
+          refundTransactionHashes: [],
+          sourceTransactionHashes: [sourceTransactionHash],
+          status: 'failure',
+          updatedAt: '2026-01-08T00:02:00.000Z',
+        },
+        verifyTransfers: Evidence.createVerifier({ db }),
+      })
+      const [record] = await FundingDeposits.listBySourceTransaction(db, {
+        depositAddressId: address.id,
+        sourceTransactionHash,
+      })
+
+      expect({ counts, record, result }).toMatchInlineSnapshot(
+        {
+          record: {
+            createdAt: expect.any(String),
+            depositAddressId: expect.any(String),
+            id: expect.any(String),
+            snapshot: { depositAddressId: expect.any(String) },
+            updatedAt: expect.any(String),
+          },
+        },
+        `
+        {
+          "counts": [
+            [
+              "funding_deposit_refund_count",
+              1,
+              {
+                "outcome": "provider_failed",
+                "provider": "relay",
+              },
+            ],
+          ],
+          "record": {
+            "createdAt": Any<String>,
+            "depositAddressId": Any<String>,
+            "detectionTrigger": "poll",
+            "environment": "production",
+            "id": Any<String>,
+            "orgId": "org_failed_reconciliation",
+            "pollObservedAt": null,
+            "projectId": null,
+            "providerOutputAmount": null,
+            "providerOutputToken": {
+              "address": "0x20c000000000000000000000b9537d11c60e8b50",
+              "currency": "USD",
+              "decimals": 6,
+              "name": "Bridged USDC (Stargate)",
+              "standard": "TIP-20",
+              "symbol": "USDC.e",
+              "tokenKey": "eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50",
+              "verified": true,
+            },
+            "providerRequestId": "relay-failed-request",
+            "providerRequestIds": [
+              "relay-failed-request",
+            ],
+            "providerState": null,
+            "providerTransactionHashes": [],
+            "providerTransferIndex": 0,
+            "retryState": null,
+            "settlementTransaction": null,
+            "settlementTransactionHash": null,
+            "snapshot": {
+              "depositAddressId": Any<String>,
+              "destinationChain": {
+                "addressFormat": "hex",
+                "id": "eip155:4217",
+                "kind": "evm",
+                "name": "Tempo",
+              },
+              "destinationToken": {
+                "address": "0x20c000000000000000000000b9537d11c60e8b50",
+                "currency": "USD",
+                "decimals": 6,
+                "name": "Bridged USDC (Stargate)",
+                "standard": "TIP-20",
+                "symbol": "USDC.e",
+                "tokenKey": "eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50",
+                "verified": true,
+              },
+              "provider": {
+                "id": "relay",
+                "name": "Relay",
+              },
+              "recipient": "0x1111111111111111111111111111111111111111",
+              "refundAddress": "0x4e4e4e4e4e4e4e4e4e4e4e4e4e4e4e4e4e4e4e4e",
+              "sender": "0x4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f",
+              "sourceAmount": {
+                "baseUnits": "1000000",
+                "currency": "USD",
+                "decimals": 6,
+                "formatted": "1",
+              },
+              "sourceChain": {
+                "addressFormat": "hex",
+                "id": "eip155:8453",
+                "kind": "evm",
+                "name": "Base",
+              },
+              "sourceToken": {
+                "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                "currency": "USD",
+                "decimals": 6,
+                "name": "USD Coin",
+                "standard": "ERC-20",
+                "symbol": "USDC",
+                "tokenKey": "eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                "verified": true,
+              },
+              "sourceTransactionHashes": [
+                "0xadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadad",
+              ],
+            },
+            "sourceChainId": "eip155:8453",
+            "sourceTransactionHash": "0xadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadad",
+            "sourceTransferIndex": 0,
+            "status": "refunding",
+            "statusReason": null,
+            "subsidyAmount": null,
+            "tempoGasPaid": null,
+            "updatedAt": Any<String>,
+            "version": 3,
+            "webhookReceivedAt": null,
+          },
+          "result": {
+            "created": 1,
+            "followUp": "delivery",
+            "terminal": false,
+            "updated": 1,
+          },
+        }
+      `,
+      )
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
   test('persists a detected deposit before source verification succeeds', async () => {
     const route = TestFunding.transferSnapshot()
     const depositAddress = `0x${'20'.repeat(20)}`
@@ -2500,6 +3739,7 @@ describe('createTracker', () => {
           createdAt: '2026-01-05T00:01:00.000Z',
           destinationTransactionHashes: [destinationTransactionHash],
           id: 'source-evidence-request',
+          refundTransactionHashes: [],
           sourceTransactionHashes: [firstSourceTransactionHash, secondSourceTransactionHash],
           status: 'success',
           updatedAt: '2026-01-05T00:02:00.000Z',