tapimo 0.15.0 → 0.18.0

package/src/internal/routes/Provider.ts

@@ -190,6 +190,18 @@ export namespace schema {
           ),
           z.meta({ examples: ['relay', 'stargate'] }),
         ),
+      recipient: z
+        .optional(z.string().check(z.minLength(1), z.maxLength(128)))
+        .check(
+          z.describe('Destination account.'),
+          z.meta({ examples: ['0x1111111111111111111111111111111111111111'] }),
+        ),
+      sender: z
+        .optional(z.string().check(z.minLength(1), z.maxLength(128)))
+        .check(
+          z.describe('Source account that will execute the swap.'),
+          z.meta({ examples: ['0x2222222222222222222222222222222222222222'] }),
+        ),
       sourceAmount: PositiveDecimal.check(
         z.describe('Positive source token amount. Base units by default, so 1 USDC is `1000000`.'),
         z.meta({ examples: ['1000000'] }),
@@ -207,7 +219,7 @@ export namespace schema {
       sourceToken: z.string().check(
         z.minLength(1),
         z.describe(
-          'Source token symbol, contract address, or Tempo token key. Lookup is scoped to `sourceChain`; non-EVM addresses are case-sensitive. An unknown token returns an empty list.',
+          'Source token symbol, address, or token key, scoped to `sourceChain`. Non-EVM addresses are case-sensitive. Unknown tokens return HTTP 400 with `route_unavailable`.',
         ),
         z.meta({
           examples: ['usdc', 'usdce', '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'],
@@ -222,6 +234,23 @@ export namespace schema {
   /** Machine-readable provider quote quality tier. */
   export const QualityTier = z.enum(['liquid', 'thin', 'unknown', 'unavailable'])
 
+  /** Public reasons a matching route cannot return a quote. */
+  export const UnavailableReason = z
+    .enum([
+      'identity_required',
+      'insufficient_liquidity',
+      'invalid_identity',
+      'price_unavailable',
+      'recipient_not_allowed',
+      'recipient_unsupported',
+      'route_unavailable',
+      'sender_not_allowed',
+    ])
+    .check(
+      z.describe('Reason the matching route could not return a quote.'),
+      z.meta({ examples: ['sender_not_allowed'] }),
+    )
+
   /** Quote data returned by a route provider. */
   export const GetQuoteResult = Schema.describe(
     z.object({
@@ -236,6 +265,7 @@ export namespace schema {
           tier: z.optional(QualityTier),
         }),
       ),
+      reason: z.optional(UnavailableReason),
       sampledAt: z.iso.datetime(),
       status: QuoteStatus,
     }),
@@ -277,6 +307,9 @@ export namespace schema {
           checkEndpoint: z
             .optional(z.string())
             .check(z.describe('Provider status endpoint for the original address request.')),
+          fixedRate: z
+            .optional(z.literal('1:1'))
+            .check(z.describe('Provider-guaranteed normalized delivery rate.')),
           requestId: z
             .string()
             .check(z.minLength(1), z.describe('Provider-issued address request identifier.')),
@@ -559,9 +592,21 @@ export declare namespace verifyDestinationDelivery {
 
   /** Destination delivery verification outcome. */
   type ReturnType =
+    | {
+        /** Recovery information for an operator when automatic delivery cannot continue. */
+        statusReason: Transfer.StatusReason
+        /** Delivery requires manual recovery. */
+        type: 'action-required'
+      }
     | { type: 'invalid' }
-    | { type: 'pending' }
     | {
+        /** Updated private index cursor to persist before the next delivery check. */
+        providerState?: Transfer.ProviderState | undefined
+        type: 'pending'
+      }
+    | {
+        /** Exact destination amount proven by the provider delivery, when it differs from the quote. */
+        destinationAmount?: string | undefined
         /** Verified destination transaction reference. */
         transactionHash: string
         /** The destination delivery matches the stored transfer terms. */
@@ -625,6 +670,8 @@ export declare namespace createDepositAddress {
     refundAddress: string
     /** Whether Tempo guarantees normalized 1:1 delivery. */
     subsidize: boolean
+    /** Maximum provider fee sponsorship in decimal USD. */
+    subsidyMaxAmount?: string | undefined
   }
 
   /** Reusable address and private provider correlation. */
@@ -964,6 +1011,8 @@ export type ProviderAttempt =
 
 /** Bounded result for one provider attempt. */
 export type ProviderAttemptResult = {
+  /** Shared cooldown applied after an upstream rate-limit response. */
+  cooldownMs?: number | undefined
   /** Wall-clock duration of the provider attempt in milliseconds. */
   durationMs: number
   /** Failure class, present only when the provider attempt failed. */
@@ -974,6 +1023,8 @@ export type ProviderAttemptResult = {
   operation: ProviderOperation
   /** Provider attempt outcome. */
   outcome: ProviderAttempt['outcome']
+  /** Whether a rate-limit failure originated locally or upstream. */
+  rateLimitSource?: 'local' | 'upstream' | undefined
 }
 
 /** A provider failure retained for bounded request diagnostics. */
@@ -1104,6 +1155,8 @@ export async function getQuotes(options: getQuotes.Options) {
             destinationChain: options.destinationChain,
             destinationToken: options.destinationToken,
             provider: options.provider,
+            recipient: options.recipient,
+            sender: options.sender,
             sourceAmount: options.sourceAmount,
             sourceAmountUnits: options.sourceAmountUnits,
             sourceChain: options.sourceChain,
@@ -1117,7 +1170,7 @@ export async function getQuotes(options: getQuotes.Options) {
           outcome: result.outcome,
           provider,
         })
-        return 'quote' in result ? result.quote : undefined
+        return result
       } catch (cause) {
         attempts.set(index, {
           cause,
@@ -1142,8 +1195,16 @@ export async function getQuotes(options: getQuotes.Options) {
     }
   }
   const quotes = results.flatMap((result) =>
-    result.status === 'fulfilled' && result.value ? [result.value] : [],
+    result.status === 'fulfilled' && result.value.quote ? [result.value.quote] : [],
   )
+  for (const result of results)
+    if (result.status === 'fulfilled' && result.value.unavailable) {
+      try {
+        options.onUnavailable?.(result.value.unavailable)
+      } catch {
+        // Observer failures must not discard completed quotes or skip outcome reporting.
+      }
+    }
   const failures = results.flatMap((result, index) =>
     result.status === 'rejected'
       ? [
@@ -1249,6 +1310,8 @@ export declare namespace getQuotes {
     onAttempt?: ((attempt: ProviderAttempt) => void) | undefined
     /** Receives the bounded request-level quote result. */
     onResult?: ((result: QuoteRequestResult) => void) | undefined
+    /** Receives a provider-neutral reason for each unavailable quote. */
+    onUnavailable?: ((reason: z.output<typeof schema.UnavailableReason>) => void) | undefined
     /** Stable non-secret tenant identity for provider-local fairness. */
     quotaKey?: string | undefined
     /** Per-provider quote timeout in milliseconds. */
@@ -1262,8 +1325,7 @@ const defaultPrepareTimeoutMs = 10_000
 const defaultQuoteTtlMs = 60_000
 
 /**
- * Provisions one reusable deposit address through the first deterministic
- * capability-enabled provider. Returns `undefined` when no route is enabled.
+ * Provisions a reusable address through the first eligible provider. Returns `undefined` without an eligible route; throws `ProviderUnavailableError` when the current quote is unavailable.
  */
 export async function createDepositAddress(
   options: createDepositAddress.Options,
@@ -1285,6 +1347,7 @@ export async function createDepositAddress(
               recipient: selected.recipient,
               refundAddress: selected.refundAddress,
               subsidize: options.subsidize,
+              subsidyMaxAmount: options.subsidyMaxAmount,
             },
             signal,
           ),
@@ -1332,7 +1395,7 @@ export async function createDepositAddress(
     } catch {
       // Observability hooks never alter provisioning behavior.
     }
-    if (cause instanceof ProviderUnavailableError) return undefined
+    if (cause instanceof ProviderUnavailableError) throw cause
     throw new ProviderQuoteError([{ cause, operation, provider: selected.provider }], [attempt])
   }
 }
@@ -1393,6 +1456,8 @@ export declare namespace createDepositAddress {
     refundAddress: string
     /** Whether Tempo guarantees normalized 1:1 delivery. */
     subsidize: boolean
+    /** Maximum provider fee sponsorship in decimal USD. */
+    subsidyMaxAmount?: string | undefined
   }
 
   /** Selected provider route and its reusable address. */
@@ -1464,20 +1529,27 @@ export async function prepareTransfer(
             basisPointScale
           if (BigInt(result.destinationAmountMin) < minimumAllowed) throw new ProviderPayloadError()
         }
-        if (result.action.type === 'evm:calls')
+        if (result.action.type === 'evm:calls' || result.action.type === 'tron:calls')
           try {
+            if (
+              result.action.type === 'tron:calls' &&
+              (candidate.sourceChain.kind !== 'tron' || !provider.validateTransferAction)
+            )
+              throw new ProviderPayloadError()
             const constraints = provider.validateTransferAction?.({
               ...parameters,
               action: result.action,
               destinationAmountMin: result.destinationAmountMin,
             })
-            Action.validateEvmCalls({
-              action: result.action,
+            const bounds = {
               nativeValues: constraints?.nativeValues,
               sourceAmount: candidate.sourceAmount.amount,
               sourceTokenAddress: candidate.sourceToken.address,
               tokenApprovals: constraints?.tokenApprovals,
-            })
+            }
+            if (result.action.type === 'tron:calls')
+              Action.validateTronCalls({ ...bounds, action: result.action })
+            else Action.validateEvmCalls({ ...bounds, action: result.action })
           } catch (cause) {
             if (cause instanceof Action.InvalidActionError) throw new ProviderPayloadError()
             throw cause
@@ -1536,14 +1608,19 @@ export async function prepareTransfer(
     throw new ProviderQuoteError(failures, attempts)
   }
 
+  const eligible = options.accept
+    ? prepared.filter(({ candidate, result }) => options.accept!(candidate, result))
+    : prepared
+  if (eligible.length === 0) return undefined
+
   // Deterministic selection: highest guaranteed minimum, then provider id.
-  prepared.sort((a, b) => {
+  eligible.sort((a, b) => {
     const delta = BigInt(b.result.destinationAmountMin) - BigInt(a.result.destinationAmountMin)
     if (delta !== 0n) return delta > 0n ? 1 : -1
     return a.provider.id < b.provider.id ? -1 : 1
   })
-  const selected = prepared[0]!
-  const bestDestinationAmount = prepared.reduce(
+  const selected = eligible[0]!
+  const bestDestinationAmount = eligible.reduce(
     (best, entry) =>
       BigInt(entry.result.destinationAmount) > BigInt(best) ? entry.result.destinationAmount : best,
     selected.result.destinationAmount,
@@ -1551,7 +1628,7 @@ export async function prepareTransfer(
   return {
     ...selected,
     bestDestinationAmount,
-    preparedCount: prepared.length,
+    preparedCount: eligible.length,
     recipient,
     sender,
   }
@@ -1560,6 +1637,8 @@ export async function prepareTransfer(
 export declare namespace prepareTransfer {
   /** Options for preparing one executable transfer. */
   type Options = getPrepareCandidates.Options & {
+    /** Tests request-specific eligibility after provider validation, before ranking. */
+    accept?: ((candidate: QuoteCandidate, result: ReturnType) => boolean) | undefined
     /** Receives one bounded observation for every provider attempt. */
     onAttempt?: ((attempt: ProviderAttempt) => void) | undefined
     /** Per-provider preparation timeout in milliseconds. */
@@ -1727,7 +1806,7 @@ export function failure(options: ProviderFailure): failure.Result {
     const code = errorCode(cause.body)
     return {
       ...(code === undefined ? {} : { code }),
-      failure: 'http',
+      failure: cause.status === 429 ? 'rate_limit' : 'http',
       id: provider.id,
       operation,
       status: cause.status,
@@ -1794,10 +1873,28 @@ export async function requestJson(url: URL, options: requestJson.Options) {
       return text
     }
   })()
-  if (!response.ok) throw new ProviderResponseError(response.status, body)
+  if (!response.ok)
+    throw new ProviderResponseError(
+      response.status,
+      body,
+      retryAfterMilliseconds(response.headers.get('retry-after')),
+    )
   return body
 }
 
+function retryAfterMilliseconds(value: string | null) {
+  if (value === null) return undefined
+  const normalized = value.trim()
+  if (/^\d+$/.test(normalized)) {
+    const seconds = Number(normalized)
+    const milliseconds = seconds * 1_000
+    return Number.isSafeInteger(milliseconds) ? milliseconds : undefined
+  }
+  const date = Date.parse(normalized)
+  if (Number.isNaN(date)) return undefined
+  return Math.max(0, date - Date.now())
+}
+
 export declare namespace requestJson {
   /** Provider request options. */
   type Options = {
@@ -1822,6 +1919,7 @@ export function unavailableResult(options: unavailableResult.Options): getQuote.
       sourceDetail: `${options.detail}:${options.message}`,
       tier: 'unavailable',
     },
+    ...(options.reason ? { reason: options.reason } : {}),
     sampledAt: options.now.toISOString(),
     status: 'unavailable',
   }
@@ -1836,6 +1934,8 @@ export declare namespace unavailableResult {
     message: string
     /** Quote sample time. */
     now: Date
+    /** Provider-neutral reason safe to explain to the caller. */
+    reason?: z.output<typeof schema.UnavailableReason> | undefined
     /** Liquidity signal source. */
     source: string
   }
@@ -1883,7 +1983,11 @@ async function quoteCandidate(
   )
   if (!result.success) throw new ProviderPayloadError()
   const quote = result.data
-  if (quote.status === 'unavailable') return { outcome: quote.status }
+  if (quote.status === 'unavailable')
+    return {
+      outcome: quote.status,
+      unavailable: quote.reason ?? 'route_unavailable',
+    }
   if (
     (quote.status !== 'available' && quote.status !== 'thin') ||
     quote.destinationAmount === undefined ||
@@ -2084,20 +2188,28 @@ function errorCode(input: unknown) {
 
 /** Formats one provider attempt for logs and aggregate metrics. */
 export function formatAttempt(attempt: ProviderAttempt): ProviderAttemptResult {
+  const details =
+    attempt.outcome === 'failed'
+      ? failure({
+          cause: attempt.cause,
+          operation: attempt.operation,
+          provider: attempt.provider,
+        })
+      : undefined
+  const responseError =
+    attempt.outcome === 'failed' && attempt.cause instanceof ProviderResponseError
+      ? attempt.cause
+      : undefined
   return {
+    ...(responseError?.cooldownMs === undefined ? {} : { cooldownMs: responseError.cooldownMs }),
     durationMs: attempt.durationMs,
-    ...(attempt.outcome === 'failed'
-      ? {
-          failure: failure({
-            cause: attempt.cause,
-            operation: attempt.operation,
-            provider: attempt.provider,
-          }).failure,
-        }
-      : {}),
+    ...(details === undefined ? {} : { failure: details.failure }),
     id: attempt.provider.id,
     operation: attempt.operation,
     outcome: attempt.outcome,
+    ...(details?.failure === 'rate_limit'
+      ? { rateLimitSource: responseError?.status === 429 ? 'upstream' : 'local' }
+      : {}),
   }
 }
 
@@ -2276,6 +2388,11 @@ export class ProviderUnavailableError extends Error {
   override name = 'RoutesProvider.ProviderUnavailableError'
 }
 
+/** Error thrown when the requested deposit amount cannot cover route fees. */
+export class AmountTooLowError extends ProviderUnavailableError {
+  override name = 'RoutesProvider.AmountTooLowError'
+}
+
 /** Error thrown internally when a provider exceeds its quote timeout. */
 export class ProviderTimeoutError extends Error {
   override name = 'RoutesProvider.ProviderTimeoutError'
@@ -2290,11 +2407,16 @@ export class ProviderRateLimitError extends Error {
 export class ProviderResponseError extends Error {
   override name = 'RoutesProvider.ProviderResponseError'
 
+  /** Effective shared cooldown applied after this response. */
+  cooldownMs?: number
+
   constructor(
     /** Provider response status. */
     readonly status: number,
     /** Parsed provider response body. */
     readonly body: unknown,
+    /** Upstream retry delay parsed from `Retry-After`, when supplied. */
+    readonly retryAfterMs?: number,
   ) {
     super(`Provider request failed with status ${status}`)
   }

package/src/internal/routes/Quota.test.ts

@@ -0,0 +1,149 @@
+import * as Store from '../Store.js'
+import * as RoutesProvider from './Provider.js'
+import * as ProviderQuota from './Quota.js'
+
+describe('check', () => {
+  test('preserves a cooldown installed while a successful check is pending', async () => {
+    const store = Store.memory()
+    const now = new Date('2026-09-24T12:00:00.000Z')
+    const options = { key: 'quota', now }
+
+    await Promise.all([
+      ProviderQuota.check(store, options),
+      ProviderQuota.block(store, { ...options, durationMs: 60_000, windowMs: 1_000 }),
+    ])
+
+    await expect(
+      ProviderQuota.check(store, { ...options, now: new Date(now.getTime() + 1) }),
+    ).rejects.toBeInstanceOf(RoutesProvider.ProviderRateLimitError)
+    await expect(
+      ProviderQuota.check(store, { ...options, now: new Date(now.getTime() + 60_000) }),
+    ).resolves.toBeUndefined()
+  })
+})
+
+describe('consume', () => {
+  test.each([10, 20])('accepts the full quota of %i under contention', async (limit) => {
+    const store = Store.memory()
+    const options = {
+      key: 'quota',
+      limit,
+      now: new Date('2026-09-24T12:00:00.000Z'),
+      windowMs: 1_000,
+    }
+    const results = await Promise.allSettled(
+      Array.from({ length: limit + 5 }, () => ProviderQuota.consume(store, options)),
+    )
+
+    expect(results.filter((result) => result.status === 'fulfilled')).toHaveLength(limit)
+    const rejected = results.filter((result) => result.status === 'rejected')
+    expect(rejected).toHaveLength(5)
+    for (const result of rejected)
+      expect(result.reason).toBeInstanceOf(RoutesProvider.ProviderRateLimitError)
+    expect(JSON.parse((await store.get(options.key))!).count).toBe(limit)
+
+    // A rejected reservation must not prevent the next window from proceeding.
+    await ProviderQuota.consume(store, {
+      ...options,
+      now: new Date(options.now.getTime() + options.windowMs),
+    })
+    expect(JSON.parse((await store.get(options.key))!).count).toBe(1)
+  })
+})
+
+describe('block', () => {
+  test('persists the longest cooldown under contention', async () => {
+    const store = Store.memory()
+    const options = {
+      key: 'quota',
+      now: new Date('2026-09-24T12:00:00.000Z'),
+      windowMs: 1_000,
+    }
+    const results = await Promise.allSettled(
+      Array.from({ length: 20 }, (_, index) =>
+        ProviderQuota.block(store, { ...options, durationMs: (index + 1) * 1_000 }),
+      ),
+    )
+
+    expect(results.filter((result) => result.status === 'fulfilled')).toHaveLength(20)
+    expect(JSON.parse((await store.get(options.key))!).blockedUntil).toBe(
+      options.now.getTime() + 20_000,
+    )
+    await expect(
+      ProviderQuota.consume(store, {
+        ...options,
+        limit: 10,
+        now: new Date(options.now.getTime() + 19_999),
+      }),
+    ).rejects.toBeInstanceOf(RoutesProvider.ProviderRateLimitError)
+    await expect(
+      ProviderQuota.consume(store, {
+        ...options,
+        limit: 10,
+        now: new Date(options.now.getTime() + 20_000),
+      }),
+    ).resolves.toBeUndefined()
+  })
+})
+
+describe('durableObject', () => {
+  test('uses one native RPC for quota state transitions', async () => {
+    const calls: string[] = []
+    let consumeAllowed = true
+    const namespace = {
+      getByName(name: string) {
+        expect(name).toBe('routes:relay:quota')
+        return {
+          async routesQuotaBlock() {
+            calls.push('block')
+          },
+          async routesQuotaCheck() {
+            calls.push('check')
+            return true
+          },
+          async routesQuotaConsume() {
+            calls.push('consume')
+            return consumeAllowed
+          },
+        }
+      },
+    } as unknown as Store.durableObject.Namespace
+    const store = ProviderQuota.durableObject(namespace, { name: 'routes:relay:quota' })
+    const now = new Date('2026-09-24T12:00:00.000Z')
+
+    await ProviderQuota.consume(store, {
+      key: 'routes:relay:quote-v2',
+      limit: 10,
+      now,
+      windowMs: 1_000,
+    })
+    await ProviderQuota.check(store, { key: 'routes:relay:adaptive', now })
+    await ProviderQuota.check(store, { key: 'routes:relay:adaptive', now })
+    await ProviderQuota.block(store, {
+      durationMs: 2_000,
+      key: 'routes:relay:adaptive',
+      now,
+      windowMs: 1_000,
+    })
+
+    expect(calls).toEqual(['consume', 'check', 'block'])
+    await expect(
+      ProviderQuota.check(store, {
+        key: 'routes:relay:adaptive',
+        now: new Date(now.getTime() + 1_000),
+      }),
+    ).rejects.toBeInstanceOf(RoutesProvider.ProviderRateLimitError)
+    expect(calls).toEqual(['consume', 'check', 'block'])
+
+    consumeAllowed = false
+    await expect(
+      ProviderQuota.consume(store, {
+        key: 'routes:relay:quote-v2',
+        limit: 10,
+        now,
+        windowMs: 1_000,
+      }),
+    ).rejects.toBeInstanceOf(RoutesProvider.ProviderRateLimitError)
+    expect(calls).toEqual(['consume', 'check', 'block', 'consume'])
+  })
+})