tapimo 0.9.0 → 0.10.1

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/index.test.ts

@@ -7,13 +7,15 @@ import * as Squid from './squid.js'
 import * as Symbiosis from './symbiosis.js'
 
 const now = () => new Date('2026-01-01T00:00:00.000Z')
+const evmUserAddress = TestFunding.relayQuoteUsers['eip155:4217']
+const solanaUserAddress = '7ZwiMrYFNCzZ4TcPkeMx7BTZSZ9jDgGR8H8Nkazhr6L1'
 const providers = [
   Across.across({
     apiKey: 'across-api-key',
     integratorId: '0xdead',
     userAddress: '0x1111111111111111111111111111111111111111',
   }),
-  Relay.relay({ userAddress: '0x1111111111111111111111111111111111111111' }),
+  Relay.relay({ userAddresses: TestFunding.relayQuoteUsers }),
   Rhino.rhino(),
   Squid.squid({
     integratorId: 'squid-integrator-id',
@@ -141,7 +143,7 @@ describe('funding providers', () => {
       apiKey: 'relay-api-key',
       fetch,
       now,
-      userAddress: '0x1111111111111111111111111111111111111111',
+      userAddresses: TestFunding.relayQuoteUsers,
     })
 
     const result = await provider.getQuote(getQuoteInput(candidate), new AbortController().signal)
@@ -192,6 +194,74 @@ describe('funding providers', () => {
     `)
   })
 
+  test('requires a Relay quote wallet for the source chain', async () => {
+    const requests: RecordedRequest[] = []
+    const candidate = quoteCandidate('relay', {
+      destinationToken: 'pathUSD',
+      sourceChain: 'solana',
+    })
+    const provider = Relay.relay({
+      fetch: recordingFetch(requests, async () => jsonResponse({})),
+      now,
+      userAddresses: { 'eip155:4217': evmUserAddress },
+    })
+
+    const result = await provider.getQuote(getQuoteInput(candidate), new AbortController().signal)
+
+    expect(requests).toHaveLength(0)
+    expect(result).toMatchObject({
+      quality: {
+        sourceDetail: 'relay:quote-v2:QUOTE_USER_NOT_CONFIGURED',
+        tier: 'unavailable',
+      },
+      status: 'unavailable',
+    })
+  })
+
+  test('uses chain-specific Relay quote wallets', async () => {
+    const requests: RecordedRequest[] = []
+    const candidate = quoteCandidate('relay', {
+      destinationToken: 'pathUSD',
+      sourceChain: 'solana',
+    })
+    const fetch = recordingFetch(requests, async () =>
+      jsonResponse({
+        details: {
+          currencyOut: { amount: '990000', minimumAmount: '980000' },
+          timeEstimate: 15,
+        },
+      }),
+    )
+    const provider = Relay.relay({
+      fetch,
+      now,
+      userAddresses: {
+        'eip155:4217': evmUserAddress,
+        'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp': solanaUserAddress,
+      },
+    })
+
+    const result = await provider.getQuote(getQuoteInput(candidate), new AbortController().signal)
+
+    expect(jsonRequestBody(requests[0])).toMatchObject({
+      destinationChainId: 4217,
+      originChainId: 792703809,
+      recipient: evmUserAddress,
+      user: solanaUserAddress,
+    })
+    expect(result).toMatchObject({ status: 'available' })
+  })
+
+  test('rejects invalid chain-specific Relay quote wallets', () => {
+    expect(() =>
+      Relay.relay({
+        userAddresses: {
+          'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp': '0x1111111111111111111111111111111111111111',
+        },
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(`[FundingProvider.ProviderConfigurationError]`)
+  })
+
   test('maps successful Squid quotes to available quote results', async () => {
     const requests: RecordedRequest[] = []
     const candidate = quoteCandidate('squid')
@@ -646,7 +716,7 @@ describe('funding providers', () => {
     try {
       const provider = Relay.relay({
         now,
-        userAddress: '0x1111111111111111111111111111111111111111',
+        userAddresses: TestFunding.relayQuoteUsers,
       })
       const result = await provider.getQuote(getQuoteInput(candidate), new AbortController().signal)
 

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

@@ -123,7 +123,6 @@ describe.skipIf(!apiKey)('relay.prepareTransfer (live)', () => {
         requestBody = JSON.parse(init.body) as Record<string, unknown>
         return globalThis.fetch(input, init)
       },
-      userAddress: sender,
     })
     result = await provider.prepareTransfer!(prepareInput(provider), new AbortController().signal)
   })
@@ -151,11 +150,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)
@@ -175,7 +171,6 @@ describe.skipIf(!apiKey)('relay.createDepositAddress (live)', () => {
         return globalThis.fetch(input, init)
       },
       subsidies: { maxAmount: '100' },
-      userAddress: sender,
     })
     result = await provider.createDepositAddress!(
       { ...depositAddressInput(provider), subsidize: true },
@@ -413,9 +408,7 @@ describe('relay.createDepositAddress', () => {
 
 describe('relay.prepareTransfer', () => {
   test('refuses methods and modes it cannot prepare', async () => {
-    const provider = Relay.relay({
-      userAddress: sender,
-    })
+    const provider = Relay.relay()
     await expect(
       provider.prepareTransfer!(
         { ...prepareInput(provider), method: 'depositAddress' },

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

@@ -1,4 +1,4 @@
-import { AbiEvent, AbiFunction, Address, Hash, Hex, RpcTransport } from 'ox'
+import { AbiEvent, AbiFunction, Address, Base58, Bytes, Hash, Hex, RpcTransport } from 'ox'
 import { createClient, custom, fallback } from 'viem'
 import { getBlockNumber, getLogs, getTransaction, getTransactionReceipt } from 'viem/actions'
 import * as z from 'zod/mini'
@@ -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({
@@ -244,11 +253,9 @@ export function parseDepositAddressRequests(value: unknown) {
 
 /** Creates a Relay funding provider backed by `/quote/v2`. */
 export function relay(options: relay.Options = {}): FundingProvider.Provider<'relay'> {
+  const userAddresses = parseUserAddresses(options.userAddresses)
   if (
-    (options.userAddress !== undefined &&
-      !Address.validate(options.userAddress, { strict: false })) ||
-    (options.recipientAddress !== undefined &&
-      !Address.validate(options.recipientAddress, { strict: false }))
+    Object.entries(userAddresses).some(([chainId, address]) => invalidUserAddress(chainId, address))
   )
     throw new FundingProvider.ProviderConfigurationError()
 
@@ -402,13 +409,22 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
       }
     },
     async getQuote({ candidate, route }, signal) {
-      if (options.userAddress === undefined)
+      const userAddress = userAddresses[route.source.chain.id]
+      if (userAddress === undefined)
         return FundingProvider.unavailableResult({
           detail: 'relay:quote-v2',
           message: 'QUOTE_USER_NOT_CONFIGURED',
           now: now(),
           source: 'providerQuote',
         })
+      const recipientAddress = userAddresses[route.destination.chain.id]
+      if (recipientAddress === undefined)
+        return FundingProvider.unavailableResult({
+          detail: 'relay:quote-v2',
+          message: 'QUOTE_RECIPIENT_NOT_CONFIGURED',
+          now: now(),
+          source: 'providerQuote',
+        })
       const destinationChainId = relayChainId(route.destination.chain)
       const sourceChainId = relayChainId(route.source.chain)
       try {
@@ -419,9 +435,9 @@ export function relay(options: relay.Options = {}): FundingProvider.Provider<'re
             destinationCurrency: candidate.destinationToken.address,
             originChainId: sourceChainId,
             originCurrency: candidate.sourceToken.address,
-            recipient: options.recipientAddress ?? options.userAddress,
+            recipient: recipientAddress,
             tradeType: 'EXACT_INPUT',
-            user: options.userAddress,
+            user: userAddress,
           },
           fetch,
           headers: options.apiKey ? { 'x-api-key': options.apiKey } : undefined,
@@ -481,6 +497,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 +517,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]
               : [],
@@ -606,12 +628,10 @@ export declare namespace relay {
     now?: (() => Date) | undefined
     /** EVM chain evidence used to accelerate authenticated provider delivery. */
     observation?: Observation | undefined
-    /** Optional recipient override; defaults to `userAddress`. */
-    recipientAddress?: string | undefined
     /** Deposit subsidy policy enabled for this integration. */
     subsidies?: Subsidy.Policy | undefined
-    /** Optional wallet address for indicative quotes. */
-    userAddress?: string | undefined
+    /** Optional source and destination quote wallets keyed by CAIP-2 chain id. */
+    userAddresses?: Readonly<Partial<Record<FundingChain.Id, string>>> | string | undefined
     /** Tempo infrastructure used to receive authenticated Relay webhooks. */
     webhook?: Webhook | undefined
   }
@@ -647,6 +667,45 @@ export declare namespace relay {
     | 'unknown_address'
 }
 
+function parseUserAddresses(value: relay.Options['userAddresses']) {
+  if (!value) return {}
+  const addresses =
+    typeof value === 'string'
+      ? (() => {
+          try {
+            return JSON.parse(value) as unknown
+          } catch {
+            throw new FundingProvider.ProviderConfigurationError()
+          }
+        })()
+      : value
+  if (!addresses || typeof addresses !== 'object' || Array.isArray(addresses))
+    throw new FundingProvider.ProviderConfigurationError()
+  return addresses as Readonly<Partial<Record<FundingChain.Id, string>>>
+}
+
+function invalidUserAddress(chainId: string, address: unknown) {
+  if (typeof address !== 'string') return true
+  if (/^eip155:\d+$/.test(chainId)) return !Address.validate(address, { strict: false })
+  if (/^solana:[1-9A-HJ-NP-Za-km-z]+$/.test(chainId)) {
+    try {
+      return Base58.toBytes(address).length !== 32
+    } catch {
+      return true
+    }
+  }
+  if (!/^tron:0x[0-9a-fA-F]+$/.test(chainId)) return true
+  try {
+    const bytes = Base58.toBytes(address)
+    if (bytes.length !== 25 || bytes[0] !== 0x41) return true
+    const payload = bytes.slice(0, 21)
+    const checksum = Hash.sha256(Hash.sha256(payload), { as: 'Bytes' }).slice(0, 4)
+    return !Bytes.isEqual(bytes.slice(21), checksum)
+  } catch {
+    return true
+  }
+}
+
 type DepositAddressObserverOptions = relay.Observation & {
   apiKey?: string | undefined
   baseUrl?: string | undefined