tapimo 0.13.0 → 0.15.0

package/src/internal/{funding → routes}/Provider.ts

@@ -5,17 +5,19 @@ import * as core_Provider from '../Provider.js'
 import * as OpenApi from '../OpenApi.js'
 import * as Schema from '../Schema.js'
 import * as Value from '../Value.js'
+import * as Viem from '../Viem.js'
 import * as Action from './Action.js'
 import type * as core_Catalog from './Catalog.js'
 import type * as core_Chain from './Chain.js'
+import * as Economics from './Economics.js'
 import type * as core_Route from './Route.js'
 import type * as core_Token from './Token.js'
 import type * as Transfer from './Transfer.js'
 
-/** Tempo token used when the caller omits `destinationToken`. */
+/** Destination token used when the caller omits `destinationToken`. */
 const defaultDestinationToken = 'usdce'
 
-/** Funding provider schemas. */
+/** Route provider schemas. */
 export namespace schema {
   /** Bounded upstream error code safe for structured logs. */
   export const ErrorCode = z.string().check(z.regex(/^[A-Za-z0-9_.:-]{1,64}$/))
@@ -36,13 +38,13 @@ export namespace schema {
     type: z.optional(z.string()),
   })
 
-  /** Positive decimal amount accepted by funding quote requests. */
+  /** Positive decimal amount accepted by route quote requests. */
   export const PositiveDecimal = z.string().check(z.regex(/^(?=.*[1-9])\d+(\.\d+)?$/))
 
-  /** Positive base-unit amount accepted by funding quote requests. */
+  /** Positive base-unit amount accepted by route quote requests. */
   export const PositiveInteger = z.string().check(z.regex(/^(?=.*[1-9])\d+$/))
 
-  /** Normalized chain reference passed to funding providers. */
+  /** Normalized chain reference passed to route providers. */
   export const ChainRef = OpenApi.component(
     Schema.describe(
       z.object({
@@ -63,12 +65,12 @@ export namespace schema {
           .string()
           .check(z.describe('Human-readable chain name.'), z.meta({ examples: ['Base'] })),
       }),
-      'A normalized chain reference for funding quotes.',
+      'A normalized chain reference for route quotes.',
     ),
-    'FundingChain',
+    'RoutesChain',
   )
 
-  /** Normalized token reference passed to funding providers. */
+  /** Normalized token reference passed to route providers. */
   export const TokenRef = OpenApi.component(
     Schema.describe(
       z.object({
@@ -113,16 +115,16 @@ export namespace schema {
         verified: z
           .boolean()
           .check(
-            z.describe('Whether Tempo recognizes this token in its funding quote inventory.'),
+            z.describe('Whether Tempo recognizes this token in its route quote inventory.'),
             z.meta({ examples: [true] }),
           ),
       }),
-      'A normalized token reference for funding quotes.',
+      'A normalized token reference for route quotes.',
     ),
-    'FundingToken',
+    'RoutesToken',
   )
 
-  /** Provider identity embedded in funding resources. */
+  /** Provider identity embedded in route resources. */
   export const ProviderRef = OpenApi.component(
     Schema.describe(
       z.object({
@@ -131,12 +133,31 @@ export namespace schema {
           .string()
           .check(z.describe('Human-readable provider name.'), z.meta({ examples: ['Relay'] })),
       }),
-      'Provider metadata embedded in a funding quote.',
+      'Provider metadata embedded in a route quote.',
     ),
-    'FundingProvider',
+    'RoutesProvider',
   )
 
-  /** Source amount unit accepted by a funding quote request. */
+  /** One token amount paid by a subsidy provider. */
+  export const Subsidy = OpenApi.component(
+    Schema.describe(
+      z.object({
+        amount: Schema.TokenAmount,
+        provider: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Stable id of the subsidy provider.'),
+            z.meta({ examples: ['relay'] }),
+          ),
+        token: TokenRef,
+      }),
+      'One token amount paid on behalf of the deposit recipient.',
+    ),
+    'RoutesSubsidy',
+  )
+
+  /** Source amount unit accepted by a route quote request. */
   export const SourceAmountUnits = z
     ._default(z.enum(['baseUnits', 'decimal']), 'baseUnits')
     .check(
@@ -144,22 +165,30 @@ export namespace schema {
       z.meta({ examples: ['baseUnits', 'decimal'] }),
     )
 
-  /** Normalized caller request passed to funding providers. */
+  /** Normalized caller request passed to route providers. */
   export const QuoteRequest = z
     .strictObject({
+      destinationChain: z
+        .optional(z.string().check(z.minLength(1)))
+        .check(
+          z.describe('Destination chain CAIP-2 id, slug, or alias. Defaults to Tempo.'),
+          z.meta({ examples: ['tempo', 'base', 'ethereum', 'eip155:4217'] }),
+        ),
       destinationToken: z
         .optional(z.string())
         .check(
-          z.describe('Tempo destination token symbol, address, or token key. Defaults to USDC.e.'),
-          z.meta({ examples: ['usdc.e'] }),
+          z.describe(
+            'Destination token symbol, address, or token key. Defaults to USDC.e for Tempo destinations.',
+          ),
+          z.meta({ examples: ['usdc.e', 'usdc'] }),
         ),
       provider: z
         .optional(z.string().check(z.minLength(1)))
         .check(
           z.describe(
-            'Only request a quote from this provider. Use an id returned by the funding providers endpoint, or omit it to query every available provider.',
+            'Only request a quote from this provider. Use an id returned by the route providers endpoint, or omit it to query every available provider.',
           ),
-          z.meta({ examples: ['relay'] }),
+          z.meta({ examples: ['relay', 'stargate'] }),
         ),
       sourceAmount: PositiveDecimal.check(
         z.describe('Positive source token amount. Base units by default, so 1 USDC is `1000000`.'),
@@ -173,19 +202,19 @@ export namespace schema {
           z.describe(
             'Source chain alias or stable id, such as `base`, `solana`, or `eip155:8453`.',
           ),
-          z.meta({ examples: ['base', 'eip155:8453'] }),
+          z.meta({ examples: ['base', 'ethereum', 'tempo', 'eip155:8453'] }),
         ),
-      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.',
-          ),
-          z.meta({ examples: ['usdc', '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'] }),
+      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.',
         ),
+        z.meta({
+          examples: ['usdc', 'usdce', '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'],
+        }),
+      ),
     })
-    .check(z.describe('Query parameters for live funding quotes into Tempo.'))
+    .check(z.describe('Query parameters for live route quotes.'))
 
   /** Provider-specific quote status for the requested amount. */
   export const QuoteStatus = z.enum(['available', 'thin', 'unknown', 'unavailable'])
@@ -193,7 +222,7 @@ export namespace schema {
   /** Machine-readable provider quote quality tier. */
   export const QualityTier = z.enum(['liquid', 'thin', 'unknown', 'unavailable'])
 
-  /** Quote data returned by a funding provider. */
+  /** Quote data returned by a route provider. */
   export const GetQuoteResult = Schema.describe(
     z.object({
       expiresAt: z.optional(z.iso.datetime()),
@@ -210,10 +239,10 @@ export namespace schema {
       sampledAt: z.iso.datetime(),
       status: QuoteStatus,
     }),
-    'Quote data returned by a funding provider.',
+    'Quote data returned by a route provider.',
   )
 
-  /** Executable preparation returned by a funding provider. */
+  /** Executable preparation returned by a route provider. */
   export const PrepareResult = z.object({
     action: Action.schema.Action,
     correlation: z.optional(
@@ -232,11 +261,12 @@ export namespace schema {
         token: z.optional(TokenRef),
       }),
     ),
+    providerState: z.optional(z.record(z.string(), z.unknown())),
     quality: GetQuoteResult.shape.quality,
     sampledAt: z.iso.datetime(),
   })
 
-  /** Reusable deposit address provisioned by a funding provider. */
+  /** Reusable deposit address provisioned by a route provider. */
   export const DepositAddressResult = z
     .object({
       address: z
@@ -269,6 +299,7 @@ export namespace schema {
     refundAmountExpected: z.optional(z.string().check(z.regex(/^\d+$/))),
     refundTransactionHashes: z.array(z.string()),
     sourceTransactionHashes: z.array(z.string()),
+    subsidy: z.optional(Subsidy),
     status: z.string().check(z.minLength(1)),
     updatedAt: z.iso.datetime(),
   })
@@ -279,8 +310,8 @@ export namespace schema {
     requests: z.array(DepositAddressRequest),
   })
 
-  /** Quote quality signals exposed to funding API callers. */
-  export const FundingQuoteQuality = OpenApi.component(
+  /** Quote quality signals exposed to routes API callers. */
+  export const RoutesQuoteQuality = OpenApi.component(
     Schema.describe(
       z.object({
         estimatedSeconds: z
@@ -289,18 +320,6 @@ export namespace schema {
             z.describe('Estimated settlement time in seconds, when known.'),
             z.meta({ examples: [2] }),
           ),
-        liquiditySource: z
-          .string()
-          .check(
-            z.describe('Provider source for the live quote quality signal.'),
-            z.meta({ examples: ['providerQuote'] }),
-          ),
-        sourceDetail: z
-          .optional(z.string())
-          .check(
-            z.describe('Provider-specific source or endpoint detail for the quality signal.'),
-            z.meta({ examples: ['providerEndpoint'] }),
-          ),
         tier: z
           .enum(['liquid', 'thin'])
           .check(
@@ -308,12 +327,12 @@ export namespace schema {
             z.meta({ examples: ['liquid'] }),
           ),
       }),
-      'Machine-readable liquidity, fee, and source signals for a successful quote.',
+      'Machine-readable quality and settlement-time signals for a successful quote.',
     ),
-    'FundingQuoteQuality',
+    'RoutesQuoteQuality',
   )
 
-  /** Provider quote freshness data exposed to funding API callers. */
+  /** Provider quote freshness data exposed to routes API callers. */
   export const QuoteDetails = OpenApi.component(
     Schema.describe(
       z.object({
@@ -330,16 +349,18 @@ export namespace schema {
             z.meta({ examples: ['2026-01-01T00:00:00Z'] }),
           ),
       }),
-      'Freshness data for a provider funding quote.',
+      'Freshness data for a provider route quote.',
     ),
-    'FundingQuoteDetails',
+    'RoutesQuoteDetails',
   )
 
-  /** Successful normalized funding quote returned to callers. */
-  export const FundingQuote = OpenApi.component(
+  /** Successful normalized route quote returned to callers. */
+  export const RoutesQuote = OpenApi.component(
     Schema.describe(
       z.object({
-        destinationAmount: Schema.TokenAmount.check(z.describe('Expected destination amount.')),
+        destinationAmount: Schema.TokenAmount.check(
+          z.describe('Expected amount received after provider deductions, including pool fees.'),
+        ),
         destinationAmountMin: z
           .optional(Schema.TokenAmount)
           .check(
@@ -347,36 +368,34 @@ export namespace schema {
               'Provider-derived minimum destination amount. Symbiosis and Squid quotes use a fixed 1% slippage tolerance.',
             ),
           ),
-        destinationChain: ChainRef.check(
-          z.describe('Destination chain, always Tempo mainnet in V1.'),
-        ),
-        destinationToken: TokenRef.check(z.describe('Tempo token expected from this quote.')),
+        destinationChain: ChainRef.check(z.describe('Chain that receives the routed token.')),
+        destinationToken: TokenRef.check(z.describe('Token expected from this quote.')),
         id: z
           .string()
           .check(
-            z.describe('Stable deterministic funding quote id.'),
+            z.describe('Stable deterministic route quote id.'),
             z.meta({ examples: ['base-usdc-tempo-usdce-relay'] }),
           ),
         provider: ProviderRef,
-        quality: FundingQuoteQuality,
+        quality: RoutesQuoteQuality,
         quote: QuoteDetails,
         sourceAmount: Schema.TokenAmount,
         sourceChain: ChainRef.check(z.describe('Chain where the caller currently holds funds.')),
         sourceToken: TokenRef.check(z.describe('Token the caller currently holds.')),
       }),
-      'One successful provider-specific funding quote.',
+      'One successful provider-specific route quote.',
     ),
-    'FundingQuote',
+    'RoutesQuote',
   )
 }
 
-/** Chain metadata declared by a funding route. */
+/** Chain metadata declared by a provider route. */
 export type Chain = core_Chain.Chain
 
-/** Token metadata declared by a funding route. */
+/** Token metadata declared by a provider route. */
 export type Token = core_Token.Resolved
 
-/** Provider ids accepted by funding quote requests. */
+/** Provider ids accepted by route quote requests. */
 export type ProviderId = string
 
 /** Provider-specific quote status for the requested amount. */
@@ -385,48 +404,83 @@ export type QuoteStatus = z.output<typeof schema.QuoteStatus>
 /** Machine-readable quote quality tier. */
 export type QualityTier = z.output<typeof schema.QualityTier>
 
-/** Normalized chain reference passed to funding providers. */
+/** Normalized chain reference passed to route providers. */
 export type ChainRef = z.output<typeof schema.ChainRef>
 
-/** Normalized token amount passed to funding providers. */
+/** Normalized token amount passed to route providers. */
 export type TokenAmount = ReturnType<typeof resolveSourceAmount>
 
-/** Normalized token reference passed to funding providers. */
+/** Normalized token reference passed to route providers. */
 export type TokenRef = z.output<typeof schema.TokenRef>
 
-/** A normalized internal candidate passed to funding quote providers. */
+/** One token amount paid by a subsidy provider. */
+export type Subsidy = z.output<typeof schema.Subsidy>
+
+/** A normalized internal candidate passed to route quote providers. */
 export type QuoteCandidate = ReturnType<typeof createQuoteCandidate>
 
 /** A normalized route candidate passed to deposit-address providers. */
 export type DepositAddressCandidate = ReturnType<typeof createDepositAddressCandidate>
 
-/** A successful normalized funding quote returned to callers. */
-export type FundingQuote = z.output<typeof schema.FundingQuote>
+/** A successful normalized route quote returned to callers. */
+export type RoutesQuote = z.output<typeof schema.RoutesQuote>
 
-/** Cache policy for a single funding quote request. */
+/** Cache policy for a single route quote request. */
 export type CachePolicy = {
   /** Whether providers should bypass their own quote or inventory caches. */
   bypass: boolean
 }
 
-/** Normalized caller request passed to funding providers. */
+/** Normalized caller request passed to route providers. */
 export type QuoteRequest = z.output<typeof schema.QuoteRequest>
 
+/** Bounded quote sample retained for request-level reliability telemetry. */
+export type QuoteSample = {
+  /** Quote age when the provider request completed. */
+  ageMs: number
+  /** Destination value loss relative to the requested source amount, in signed basis points. */
+  customerValueLossBps?: number | undefined
+  /** Destination chain in the quoted corridor. */
+  destinationChain: string
+  /** Destination token in the quoted corridor. */
+  destinationToken: string
+  /** Amount the provider timestamp is ahead of the API clock. */
+  futureSkewMs: number
+  /** Provider that returned the quote. */
+  provider: string
+  /** Source chain in the quoted corridor. */
+  sourceChain: string
+  /** Source token in the quoted corridor. */
+  sourceToken: string
+}
+
+/** Request-level result used to measure quote availability and freshness. */
+export type QuoteRequestResult = {
+  /** Number of configured route candidates matching the request. */
+  candidateCount: number
+  /** Bounded request outcome for quote-availability measurement. */
+  outcome: 'available' | 'failed' | 'unavailable' | 'unsupported'
+  /** Successful provider quote samples returned to the caller. */
+  quotes: readonly QuoteSample[]
+}
+
 /** Contract of the provider `getQuote` method. */
 export declare namespace getQuote {
-  /** Input passed to a funding provider for one curated quote candidate. */
+  /** Input passed to a route provider for one curated quote candidate. */
   type Parameters = {
     /** Curated candidate selected for live provider quoting. */
     candidate: QuoteCandidate
     /** Cache policy for provider-side discovery and quote lookups. */
     cache: CachePolicy
-    /** Destination chain, always Tempo mainnet in V1. */
+    /** Chain that receives the routed token. */
     destinationChain: ChainRef
-    /** Tempo token expected from this quote. */
+    /** Token expected from this quote. */
     destinationToken: TokenRef
+    /** Stable non-secret tenant identity for provider-local fairness. */
+    quotaKey?: string | undefined
     /** Normalized caller request that produced this quote candidate. */
     request: QuoteRequest
-    /** Canonical funding route selected for this quote candidate. */
+    /** Canonical provider route selected for this quote candidate. */
     route: core_Route.Route
     /** Source amount in base units and display form. */
     sourceAmount: TokenAmount
@@ -436,7 +490,7 @@ export declare namespace getQuote {
     sourceToken: TokenRef
   }
 
-  /** Quote data returned by a funding provider. */
+  /** Quote data returned by a route provider. */
   type ReturnType = z.output<typeof schema.GetQuoteResult>
 }
 
@@ -450,23 +504,23 @@ export declare namespace prepareTransfer {
     requestId: string
   }
 
-  /** Input passed to a funding provider preparing one executable transfer. */
+  /** Input passed to a route provider preparing one executable transfer. */
   type Parameters = {
     /** Curated candidate selected for preparation. */
     candidate: QuoteCandidate
-    /** Funding method the caller selected. */
+    /** Route method the caller selected. */
     method: Transfer.Method
     /** Amount mode the caller selected. */
     mode: Transfer.Mode
     /** Final beneficiary on the destination chain. */
     recipient: string
-    /** Source-chain account that signs the funding action. */
+    /** Source-chain account that signs the route action. */
     sender: string
     /** Caller slippage bound in basis points. */
     slippageBps?: number | undefined
   }
 
-  /** Executable preparation returned by a funding provider. */
+  /** Executable preparation returned by a route provider. */
   type ReturnType = z.output<typeof schema.PrepareResult>
 }
 
@@ -476,15 +530,87 @@ export declare namespace validateTransferAction {
   type Parameters = prepareTransfer.Parameters & {
     /** Executable action returned by the provider. */
     action: Action.Action
+    /** Minimum destination amount encoded by the provider action. */
+    destinationAmountMin: string
   }
 
   /** Provider-specific constraints established by validation. */
   type ReturnType = {
     /** Exact native values independently validated against provider calldata. */
     nativeValues?: readonly Action.NativeValue[] | undefined
+    /** Exact additional token approvals independently validated against provider calldata. */
+    tokenApprovals?: readonly Action.TokenApproval[] | undefined
   }
 }
 
+/** Contract for provider-specific destination delivery verification. */
+export declare namespace verifyDestinationDelivery {
+  /** Stored transfer terms and provider evidence. */
+  type Parameters = {
+    /** Configured chain that receives the provider delivery. */
+    destinationChain: Chain
+    /** Private provider state captured while preparing and registering the transfer. */
+    providerState?: Transfer.ProviderState | undefined
+    /** Configured chain containing the submitted transaction. */
+    sourceChain: Chain
+    /** Stored public transfer terms. */
+    transfer: Transfer.Snapshot
+  }
+
+  /** Destination delivery verification outcome. */
+  type ReturnType =
+    | { type: 'invalid' }
+    | { type: 'pending' }
+    | {
+        /** Verified destination transaction reference. */
+        transactionHash: string
+        /** The destination delivery matches the stored transfer terms. */
+        type: 'verified'
+      }
+}
+
+/** Contract for provider-specific source transaction verification. */
+export declare namespace verifySourceTransaction {
+  /** Stored transfer terms and submitted source transaction. */
+  type Parameters = {
+    /** Configured chain that receives the provider delivery. */
+    destinationChain: Chain
+    /** Private provider state captured while preparing the transfer. */
+    providerState?: Transfer.ProviderState | undefined
+    /** Current configuration for the stored provider route. */
+    routeConfiguration?: core_Catalog.Configuration | undefined
+    /** Configured chain containing the submitted transaction. */
+    sourceChain: Chain
+    /** Submitted transaction reference. */
+    transactionHash: string
+    /** Stored public transfer terms. */
+    transfer: Transfer.Snapshot
+  }
+
+  /** Source transaction verification outcome. */
+  type ReturnType =
+    | { type: 'invalid' }
+    | { type: 'pending' }
+    | {
+        /** Private provider state retained while awaiting replacement evidence. */
+        providerState: Transfer.ProviderState
+        /** Previously verified source evidence left the canonical chain. */
+        type: 'reorged'
+      }
+    | {
+        /** The transaction supports the transfer but does not execute it. */
+        type: 'related'
+      }
+    | {
+        /** Exact destination amount observed in the source transaction, when provider fees changed after preparation. */
+        destinationAmount?: string | undefined
+        /** Private provider evidence retained for reconciliation. */
+        providerState?: Transfer.ProviderState | undefined
+        /** The transaction matches the stored transfer terms. */
+        type: 'verified'
+      }
+}
+
 /** Contract of the provider `createDepositAddress` method. */
 export declare namespace createDepositAddress {
   /** Input passed to a provider provisioning one reusable deposit address. */
@@ -513,8 +639,12 @@ export declare namespace listDepositAddressRequests {
     address: string
     /** Opaque provider cursor returned by the previous page. */
     continuation?: string | undefined
+    /** Token delivered by the provider, when needed to identify a subsidy payment. */
+    destinationToken?: TokenRef | undefined
     /** Existing provider request to refresh directly. */
     requestId?: string | undefined
+    /** Token received by the provider, when needed to identify a subsidy payment. */
+    sourceToken?: TokenRef | undefined
   }
 
   /** One page of normalized provider requests. */
@@ -577,13 +707,15 @@ export declare namespace observeDepositAddressRequest {
       | {
           /** Verified destination transaction references. */
           destinationTransactionHashes: readonly string[]
+          /** Token amount paid by the provider for this request. */
+          subsidy?: z.output<typeof schema.Subsidy> | undefined
           /** Authenticated provider delivery was observed onchain. */
           type: 'verified'
         }
     )
 }
 
-/** Optional webhook capability implemented by a complete funding integration. */
+/** Optional webhook capability implemented by a complete route integration. */
 export type Webhook = {
   /** Authenticates, resolves, and enqueues one provider status event. */
   receive(input: Webhook.receive.Parameters): Promise<Webhook.receive.ReturnType>
@@ -591,11 +723,11 @@ export type Webhook = {
   verify(input: Webhook.verify.Parameters): Webhook.verify.ReturnType
 }
 
-/** Contracts for a funding provider webhook capability. */
+/** Contracts for a route provider webhook capability. */
 export declare namespace Webhook {
   /** Contracts for receiving one authenticated provider webhook. */
   namespace receive {
-    /** Raw provider webhook request passed to a funding integration. */
+    /** Raw provider webhook request passed to a route integration. */
     type Parameters = {
       /** Exact request body bytes decoded as UTF-8. */
       body: string
@@ -603,9 +735,9 @@ export declare namespace Webhook {
       headers: Headers
     }
 
-    /** Durable queue message emitted for one authenticated funding status hint. */
+    /** Durable queue message emitted for one authenticated routes status hint. */
     type Dispatchable = {
-      /** Stored funding deposit address id. */
+      /** Stored route deposit address id. */
       addressId: string
       /** Bounded follow-up state for work awaiting provider or settlement confirmation. */
       followUp?: FollowUp | undefined
@@ -616,7 +748,7 @@ export declare namespace Webhook {
       /** Mechanism that requested reconciliation. */
       trigger: 'chain' | 'manual' | 'poll' | 'webhook'
       /** Reconciliation queue message discriminator. */
-      type: 'funding:deposit-address:reconcile'
+      type: 'routes:deposit-address:reconcile'
       /** Authenticated provider webhook timing carried into reconciliation. */
       webhookTiming?: WebhookTiming | undefined
     }
@@ -649,7 +781,7 @@ export declare namespace Webhook {
       trigger?: Dispatchable['trigger'] | undefined
     }
 
-    /** Safe disposition of one authenticated funding provider webhook. */
+    /** Safe disposition of one authenticated route provider webhook. */
     type ReturnType =
       | { addressId: string; type: 'queued' }
       | { type: 'ignored' }
@@ -658,10 +790,10 @@ export declare namespace Webhook {
 
   /** Contracts for verifying one provider webhook. */
   namespace verify {
-    /** Raw provider webhook request passed to a funding integration. */
+    /** Raw provider webhook request passed to a route integration. */
     type Parameters = receive.Parameters
 
-    /** Authenticated provider hint extracted from a funding webhook. */
+    /** Authenticated provider hint extracted from a routes webhook. */
     type ReturnType = {
       /** Reusable provider address, when the provider attributed one. */
       address?: string | undefined
@@ -677,14 +809,14 @@ export declare namespace Webhook {
   }
 }
 
-/** A funding provider descriptor and live quote implementation. */
-export type Provider<id extends string = string> = core_Provider.Provider<id, 'funding'> & {
-  /** Provisions a reusable funding deposit address, when supported. */
+/** A route provider descriptor and live quote implementation. */
+export type Provider<id extends string = string> = core_Provider.Provider<id, 'routes'> & {
+  /** Provisions a reusable route deposit address, when supported. */
   createDepositAddress?(
     input: createDepositAddress.Parameters,
     signal: AbortSignal,
   ): Promise<createDepositAddress.ReturnType>
-  /** Requests a live funding quote. */
+  /** Requests a live route quote. */
   getQuote(input: getQuote.Parameters, signal: AbortSignal): Promise<getQuote.ReturnType>
   /** Lists requests discovered for a reusable deposit address, when supported. */
   listDepositAddressRequests?(
@@ -696,7 +828,7 @@ export type Provider<id extends string = string> = core_Provider.Provider<id, 'f
     input: observeDepositAddressRequest.Parameters,
     signal: AbortSignal,
   ): Promise<observeDepositAddressRequest.ReturnType>
-  /** Prepares an executable funding transfer, when the provider supports it. */
+  /** Prepares an executable route transfer, when the provider supports it. */
   prepareTransfer?(
     input: prepareTransfer.Parameters,
     signal: AbortSignal,
@@ -705,72 +837,107 @@ export type Provider<id extends string = string> = core_Provider.Provider<id, 'f
   validateTransferAction?(
     input: validateTransferAction.Parameters,
   ): validateTransferAction.ReturnType
+  /** Verifies destination delivery for a registered transfer, when supported. */
+  verifyDestinationDelivery?(
+    input: verifyDestinationDelivery.Parameters,
+    signal: AbortSignal,
+  ): Promise<verifyDestinationDelivery.ReturnType>
+  /** Verifies a submitted source transaction, when supported. */
+  verifySourceTransaction?(
+    input: verifySourceTransaction.Parameters,
+    signal: AbortSignal,
+  ): Promise<verifySourceTransaction.ReturnType>
   /** Receives authenticated provider status events, when configured. */
   webhook?: Webhook | undefined
 }
 
-/** Defines a funding provider from its identity and quote implementation. */
+/** Defines a route provider from its identity and quote implementation. */
 export function from<const id extends string>(options: from.Options<id>): Provider<id> {
   if (options.id !== normalizeInput(options.id) || options.id.length === 0)
     throw new ProviderConfigurationError('Provider ids must be lowercase and trimmed.')
-  return core_Provider.from({ ...options, type: 'funding' })
+  return core_Provider.from({ ...options, type: 'routes' })
 }
 
 export declare namespace from {
-  /** Funding provider definition. */
+  /** Route provider definition. */
   type Options<id extends string> = Omit<Provider<id>, 'type'>
 }
 
-/** Narrows a registered provider to a funding provider. */
+/** Narrows a registered provider to a route provider. */
 export function is(provider: core_Provider.Provider): provider is Provider {
   return (
-    provider.type === 'funding' && 'getQuote' in provider && typeof provider.getQuote === 'function'
+    provider.type === 'routes' && 'getQuote' in provider && typeof provider.getQuote === 'function'
   )
 }
 
-/** Narrows a funding provider to one that prepares executable transfers. */
+/** Narrows a route provider to one that prepares executable transfers. */
 export function canPrepareTransfer(provider: Provider): provider is Provider & {
   prepareTransfer: NonNullable<Provider['prepareTransfer']>
 } {
   return typeof provider.prepareTransfer === 'function'
 }
 
-/** Narrows a funding provider to one that provisions reusable deposit addresses. */
+/** Narrows a route provider to one that provisions reusable deposit addresses. */
 export function canCreateDepositAddress(provider: Provider): provider is Provider & {
   createDepositAddress: NonNullable<Provider['createDepositAddress']>
 } {
   return typeof provider.createDepositAddress === 'function'
 }
 
-/** Narrows a funding provider to one that tracks reusable deposit addresses. */
+/** Narrows a route provider to one that tracks reusable deposit addresses. */
 export function canListDepositAddressRequests(provider: Provider): provider is Provider & {
   listDepositAddressRequests: NonNullable<Provider['listDepositAddressRequests']>
 } {
   return typeof provider.listDepositAddressRequests === 'function'
 }
 
-/** Narrows a funding provider to one that observes reusable-address delivery onchain. */
+/** Narrows a route provider to one that observes reusable-address delivery onchain. */
 export function canObserveDepositAddressRequest(provider: Provider): provider is Provider & {
   observeDepositAddressRequest: NonNullable<Provider['observeDepositAddressRequest']>
 } {
   return typeof provider.observeDepositAddressRequest === 'function'
 }
 
-/** Narrows a funding provider to one with authenticated webhook receipt. */
+/** Narrows a route provider to one that reconciles registered transfers. */
+export function canReconcileTransfer(provider: Provider): provider is Provider & {
+  verifyDestinationDelivery: NonNullable<Provider['verifyDestinationDelivery']>
+  verifySourceTransaction: NonNullable<Provider['verifySourceTransaction']>
+} {
+  return (
+    typeof provider.verifyDestinationDelivery === 'function' &&
+    typeof provider.verifySourceTransaction === 'function'
+  )
+}
+
+/** Narrows a route provider to one that verifies submitted source transactions. */
+export function canVerifySourceTransaction(provider: Provider): provider is Provider & {
+  verifySourceTransaction: NonNullable<Provider['verifySourceTransaction']>
+} {
+  return typeof provider.verifySourceTransaction === 'function'
+}
+
+/** Narrows a route provider to one with authenticated webhook receipt. */
 export function canReceiveWebhook(provider: Provider): provider is Provider & {
   webhook: Webhook
 } {
   return provider.webhook !== undefined
 }
 
-/** Funding provider method recorded by request diagnostics. */
+/** Route provider method recorded by operational telemetry. */
 export type ProviderOperation =
   | 'createDepositAddress'
   | 'getQuote'
   | 'listDepositAddressRequests'
+  | 'observeDepositAddressRequest'
   | 'prepareTransfer'
+  | 'receiveWebhook'
+  | 'verifyDestinationDelivery'
+  | 'verifySourceTransaction'
+
+/** Route provider identity retained by bounded operation telemetry. */
+export type ProviderIdentity = Pick<Provider, 'id'>
 
-/** One provider attempt made while resolving a funding quote request. */
+/** One timed route provider operation. */
 export type ProviderAttempt =
   | {
       /** Wall-clock duration of the provider attempt in milliseconds. */
@@ -778,9 +945,9 @@ export type ProviderAttempt =
       /** Provider method invoked by the attempt. */
       operation: ProviderOperation
       /** Successful or expected-unavailable provider outcome. */
-      outcome: 'available' | 'thin' | 'unavailable'
-      /** Provider that handled the quote candidate. */
-      provider: Provider
+      outcome: 'available' | 'success' | 'thin' | 'unavailable'
+      /** Provider that handled the operation. */
+      provider: ProviderIdentity
     }
   | {
       /** Error thrown by the provider boundary. */
@@ -791,8 +958,8 @@ export type ProviderAttempt =
       operation: ProviderOperation
       /** Failed provider outcome. */
       outcome: 'failed'
-      /** Provider that handled the quote candidate. */
-      provider: Provider
+      /** Provider that handled the operation. */
+      provider: ProviderIdentity
     }
 
 /** Bounded result for one provider attempt. */
@@ -816,7 +983,52 @@ export type ProviderFailure = {
   /** Provider method that failed. */
   operation: ProviderOperation
   /** Provider that failed. */
-  provider: Provider
+  provider: ProviderIdentity
+}
+
+/** Observes one provider operation without changing its result. */
+export async function observe<const result>(
+  provider: ProviderIdentity,
+  fn: () => Promise<result>,
+  options: observe.Options,
+): Promise<result> {
+  const start = performance.now()
+  const report = (attempt: ProviderAttempt) => {
+    try {
+      options.onAttempt(formatAttempt(attempt))
+    } catch {
+      // Observability hooks never alter provider behavior.
+    }
+  }
+  try {
+    const value = await fn()
+    report({
+      durationMs: performance.now() - start,
+      operation: options.operation,
+      outcome: 'success',
+      provider,
+    })
+    return value
+  } catch (cause) {
+    report({
+      cause,
+      durationMs: performance.now() - start,
+      operation: options.operation,
+      outcome: 'failed',
+      provider,
+    })
+    throw cause
+  }
+}
+
+export declare namespace observe {
+  /** Provider operation observation configuration. */
+  type Options = {
+    /** Receives the bounded provider operation result. */
+    onAttempt: (result: ProviderAttemptResult) => void
+    /** Stable provider method identifier. */
+    operation: ProviderOperation
+  }
 }
 
 // Slow provider responses can still contain valid quotes; keep the boundary
@@ -847,14 +1059,14 @@ export function getChains(options: getChains.Options) {
 export declare namespace getChains {
   /** Options for getting provider-supported source chains. */
   type Options = {
-    /** Compiled funding catalog containing provider routes. */
+    /** Compiled route catalog containing provider routes. */
     catalog: core_Catalog.Snapshot
     /** Providers whose routes contribute source chains and tokens. */
     providers: readonly Provider[]
   }
 }
 
-/** Returns the supplied funding quote providers. */
+/** Returns the supplied route quote providers. */
 export function getProviders(options: getProviders.Options) {
   return options.providers
     .filter((provider) => (options.catalog.routesByProvider.get(provider.id)?.length ?? 0) > 0)
@@ -864,14 +1076,14 @@ export function getProviders(options: getProviders.Options) {
 export declare namespace getProviders {
   /** Options for getting providers. */
   type Options = {
-    /** Compiled funding catalog containing provider routes. */
+    /** Compiled route catalog containing provider routes. */
     catalog: core_Catalog.Snapshot
-    /** Funding providers included in this deployment. */
+    /** Route providers included in this deployment. */
     providers: readonly Provider[]
   }
 }
 
-/** Returns successful live funding quotes from the supplied providers. */
+/** Returns successful live route quotes from the supplied providers. */
 export async function getQuotes(options: getQuotes.Options) {
   const providers = options.providers ?? []
   const operation = 'getQuote' satisfies ProviderOperation
@@ -887,7 +1099,9 @@ export async function getQuotes(options: getQuotes.Options) {
         const result = await quoteCandidate(candidate, {
           cache: options.cache ?? { bypass: false },
           provider,
+          quotaKey: options.quotaKey ?? 'public:anonymous',
           request: {
+            destinationChain: options.destinationChain,
             destinationToken: options.destinationToken,
             provider: options.provider,
             sourceAmount: options.sourceAmount,
@@ -924,7 +1138,7 @@ export async function getQuotes(options: getQuotes.Options) {
     try {
       options.onAttempt?.(attempt)
     } catch {
-      // Observability hooks never alter funding quote behavior.
+      // Observability hooks never alter route quote behavior.
     }
   }
   const quotes = results.flatMap((result) =>
@@ -941,6 +1155,37 @@ export async function getQuotes(options: getQuotes.Options) {
         ]
       : [],
   )
+  const outcome = (() => {
+    if (quotes.length > 0) return 'available'
+    if (candidates.length === 0) return 'unsupported'
+    if (failures.length > 0) return 'failed'
+    return 'unavailable'
+  })()
+  try {
+    options.onResult?.({
+      candidateCount: candidates.length,
+      outcome,
+      quotes: quotes.map((quote) => {
+        const ageMs = Date.now() - Date.parse(quote.quote.sampledAt)
+        const customerValueLossBps = Economics.differenceBps({
+          reference: quote.sourceAmount,
+          value: quote.destinationAmount,
+        })
+        return {
+          ageMs: Math.max(0, ageMs),
+          ...(customerValueLossBps === undefined ? {} : { customerValueLossBps }),
+          destinationChain: quote.destinationChain.id,
+          destinationToken: quote.destinationToken.tokenKey,
+          futureSkewMs: Math.max(0, -ageMs),
+          provider: quote.provider.id,
+          sourceChain: quote.sourceChain.id,
+          sourceToken: quote.sourceToken.tokenKey,
+        }
+      }),
+    })
+  } catch {
+    // Reliability telemetry never alters route quote behavior.
+  }
   if (quotes.length === 0 && failures.length > 0) throw new ProviderQuoteError(failures, values)
   return quotes
 }
@@ -954,7 +1199,8 @@ export function getQuoteCandidates(options: getQuoteCandidates.Options) {
   if (!amount.success) throw new InvalidAmountError()
   const sourceChain = resolveSourceChain(options.sourceChain, catalog)
   const sourceToken = resolveSourceToken(sourceChain, options.sourceToken, catalog)
-  const destination = resolveDestinationToken(options.destinationToken, catalog)
+  const destinationChain = resolveDestinationChain(options.destinationChain ?? 'tempo', catalog)
+  const destination = resolveDestinationToken(destinationChain, options.destinationToken, catalog)
   const provider = options.provider ? resolveProvider(options.provider, providers) : undefined
 
   if (providers.length === 0) return []
@@ -985,22 +1231,26 @@ export function getQuoteCandidates(options: getQuoteCandidates.Options) {
 }
 
 export declare namespace getQuoteCandidates {
-  /** Options for selecting funding quote candidates. */
+  /** Options for selecting route quote candidates. */
   type Options = QuoteRequest & {
-    /** Compiled funding catalog containing provider routes. */
+    /** Compiled route catalog containing provider routes. */
     catalog: core_Catalog.Snapshot
-    /** Funding providers considered by the request. */
+    /** Route providers considered by the request. */
     providers: readonly Provider[]
   }
 }
 
 export declare namespace getQuotes {
-  /** Options for requesting live funding quotes. */
+  /** Options for requesting live route quotes. */
   type Options = getQuoteCandidates.Options & {
     /** Cache policy for provider-side discovery and quote lookups. */
     cache?: CachePolicy | undefined
     /** Receives one bounded observation for every provider attempt. */
     onAttempt?: ((attempt: ProviderAttempt) => void) | undefined
+    /** Receives the bounded request-level quote result. */
+    onResult?: ((result: QuoteRequestResult) => void) | undefined
+    /** Stable non-secret tenant identity for provider-local fairness. */
+    quotaKey?: string | undefined
     /** Per-provider quote timeout in milliseconds. */
     providerTimeoutMs?: number | undefined
   }
@@ -1020,18 +1270,8 @@ export async function createDepositAddress(
 ): Promise<createDepositAddress.Selection | undefined> {
   const operation = 'createDepositAddress' satisfies ProviderOperation
   if (!schema.PositiveInteger.safeParse(options.amount).success) throw new InvalidAmountError()
-  const candidates = getDepositAddressCandidates(options).sort((a, b) =>
-    a.provider.id.localeCompare(b.provider.id),
-  )
-  const selected = candidates[0]
+  const selected = selectDepositAddress(options)
   if (!selected) return undefined
-  const recipient = normalizeAccountAddress(options.recipient, selected.candidate.destinationChain)
-  const refundAddress = normalizeAccountAddress(
-    options.refundAddress,
-    selected.candidate.sourceChain,
-  )
-  if (!recipient) throw new ProviderPayloadError()
-  if (!refundAddress) throw new InvalidRefundAddressError()
 
   const start = performance.now()
   try {
@@ -1042,8 +1282,8 @@ export async function createDepositAddress(
             {
               amount: options.amount,
               candidate: selected.candidate,
-              recipient,
-              refundAddress,
+              recipient: selected.recipient,
+              refundAddress: selected.refundAddress,
               subsidize: options.subsidize,
             },
             signal,
@@ -1070,7 +1310,7 @@ export async function createDepositAddress(
     } catch {
       // Observability hooks never alter provisioning behavior.
     }
-    return { ...selected, recipient, refundAddress, result }
+    return { ...selected, result }
   } catch (cause) {
     const attempt: ProviderAttempt =
       cause instanceof ProviderUnavailableError
@@ -1097,6 +1337,47 @@ export async function createDepositAddress(
   }
 }
 
+/** Selects and normalizes the deterministic reusable-address route without provisioning it. */
+export function selectDepositAddress(
+  options: selectDepositAddress.Options,
+): selectDepositAddress.Result | undefined {
+  const candidates = getDepositAddressCandidates(options).sort((a, b) =>
+    a.provider.id.localeCompare(b.provider.id),
+  )
+  const selected = candidates[0]
+  if (!selected) return undefined
+  const recipient = normalizeAccountAddress(options.recipient, selected.candidate.destinationChain)
+  const refundAddress = normalizeAccountAddress(
+    options.refundAddress,
+    selected.candidate.sourceChain,
+  )
+  if (!recipient) throw new ProviderPayloadError()
+  if (!refundAddress) throw new InvalidRefundAddressError()
+  return { ...selected, recipient, refundAddress }
+}
+
+export declare namespace selectDepositAddress {
+  /** Route and accounts used to select one reusable-address provider. */
+  type Options = getDepositAddressCandidates.Options & {
+    /** Final beneficiary on Tempo. */
+    recipient: string
+    /** Source-chain account that receives refunds. */
+    refundAddress: string
+  }
+
+  /** Deterministic provider route with normalized accounts. */
+  type Result = {
+    /** Curated reusable-address route selected for provisioning. */
+    candidate: DepositAddressCandidate
+    /** Provider selected for the reusable address. */
+    provider: ReturnType<typeof getDepositAddressCandidates>[number]['provider']
+    /** Normalized final beneficiary on Tempo. */
+    recipient: string
+    /** Normalized source-chain refund account. */
+    refundAddress: string
+  }
+}
+
 export declare namespace createDepositAddress {
   /** Options for provisioning one reusable deposit address. */
   type Options = getDepositAddressCandidates.Options & {
@@ -1141,6 +1422,11 @@ export async function prepareTransfer(
   const operation = 'prepareTransfer' satisfies ProviderOperation
   const candidates = getPrepareCandidates(options)
   if (candidates.length === 0) return undefined
+  const first = candidates[0]!
+  const recipient = normalizeAccountAddress(options.recipient, first.candidate.destinationChain)
+  if (!recipient) throw new InvalidRecipientAddressError()
+  const sender = normalizeAccountAddress(options.sender, first.candidate.sourceChain)
+  if (!sender) throw new InvalidSenderAddressError()
 
   const attempts: ProviderAttempt[] = []
   const results = await Promise.allSettled(
@@ -1151,8 +1437,8 @@ export async function prepareTransfer(
           candidate,
           method: options.method,
           mode: options.mode,
-          recipient: options.recipient,
-          sender: options.sender,
+          recipient,
+          sender,
           slippageBps: options.slippageBps,
         }
         const parsed = schema.PrepareResult.safeParse(
@@ -1183,12 +1469,14 @@ export async function prepareTransfer(
             const constraints = provider.validateTransferAction?.({
               ...parameters,
               action: result.action,
+              destinationAmountMin: result.destinationAmountMin,
             })
             Action.validateEvmCalls({
               action: result.action,
               nativeValues: constraints?.nativeValues,
               sourceAmount: candidate.sourceAmount.amount,
               sourceTokenAddress: candidate.sourceToken.address,
+              tokenApprovals: constraints?.tokenApprovals,
             })
           } catch (cause) {
             if (cause instanceof Action.InvalidActionError) throw new ProviderPayloadError()
@@ -1254,7 +1542,19 @@ export async function prepareTransfer(
     if (delta !== 0n) return delta > 0n ? 1 : -1
     return a.provider.id < b.provider.id ? -1 : 1
   })
-  return prepared[0]!
+  const selected = prepared[0]!
+  const bestDestinationAmount = prepared.reduce(
+    (best, entry) =>
+      BigInt(entry.result.destinationAmount) > BigInt(best) ? entry.result.destinationAmount : best,
+    selected.result.destinationAmount,
+  )
+  return {
+    ...selected,
+    bestDestinationAmount,
+    preparedCount: prepared.length,
+    recipient,
+    sender,
+  }
 }
 
 export declare namespace prepareTransfer {
@@ -1266,7 +1566,7 @@ export declare namespace prepareTransfer {
     providerTimeoutMs?: number | undefined
     /** Final beneficiary on the destination chain. */
     recipient: string
-    /** Source-chain account that signs the funding action. */
+    /** Source-chain account that signs the route action. */
     sender: string
     /** Caller slippage bound in basis points. */
     slippageBps?: number | undefined
@@ -1274,12 +1574,20 @@ export declare namespace prepareTransfer {
 
   /** The selected preparation with a guaranteed expiry. */
   type Selection = {
+    /** Highest expected destination amount returned by a successful candidate. */
+    bestDestinationAmount: string
     /** Curated candidate the preparation was produced for. */
     candidate: QuoteCandidate
+    /** Number of successful preparations considered for automatic selection. */
+    preparedCount: number
     /** Provider that produced the selected preparation. */
     provider: Provider
+    /** Normalized final beneficiary on the destination chain. */
+    recipient: string
     /** The preparation, with a default expiry applied when the provider gave none. */
     result: prepareTransfer.ReturnType & { expiresAt: string }
+    /** Normalized source-chain account that signs the route action. */
+    sender: string
   }
 }
 
@@ -1315,13 +1623,13 @@ export function getDepositAddressCandidates(options: getDepositAddressCandidates
 export declare namespace getDepositAddressCandidates {
   /** Options for selecting reusable deposit-address routes. */
   type Options = {
-    /** Compiled funding catalog containing provider routes and capabilities. */
+    /** Compiled route catalog containing provider routes and capabilities. */
     catalog: core_Catalog.Snapshot
     /** Tempo destination chain selected by app composition. */
     destinationChainId: number
     /** Tempo destination token symbol, contract address, or token key. */
     destinationToken: string
-    /** Funding providers considered by the request. */
+    /** Route providers considered by the request. */
     providers: readonly Provider[]
     /** Source chain CAIP-2 id, slug, or alias. */
     sourceChain: string
@@ -1339,14 +1647,14 @@ export function getPrepareCandidates(options: getPrepareCandidates.Options) {
   const amount = schema.PositiveInteger.safeParse(options.sourceAmount)
   if (!amount.success) throw new InvalidAmountError()
   const sourceChain = resolveSourceChain(options.sourceChain, options.catalog)
-  const destinationChainId = `eip155:${options.destinationChainId}`
+  const destinationChain = resolveDestinationChain(options.destinationChain, options.catalog)
   const selectedProvider = options.provider
     ? resolveProvider(options.provider, options.providers)
     : undefined
 
   return options.catalog.routes.flatMap((entry) => {
     if (entry.route.source.chain.id !== sourceChain.id) return []
-    if (entry.route.destination.chain.id !== destinationChainId) return []
+    if (entry.route.destination.chain.id !== destinationChain.id) return []
     if (!matchesToken(entry.route.source, options.sourceToken)) return []
     if (!matchesToken(entry.route.destination, options.destinationToken)) return []
     if (!entry.capabilities?.transfer?.modes.includes(options.mode)) return []
@@ -1376,19 +1684,19 @@ export function getPrepareCandidates(options: getPrepareCandidates.Options) {
 export declare namespace getPrepareCandidates {
   /** Options for selecting preparation candidates. */
   type Options = {
-    /** Compiled funding catalog containing provider routes and capabilities. */
+    /** Compiled route catalog containing provider routes and capabilities. */
     catalog: core_Catalog.Snapshot
-    /** Tempo destination chain selected by app composition. */
-    destinationChainId: number
-    /** Tempo destination token symbol, contract address, or token key. */
+    /** Destination chain CAIP-2 id, slug, or alias. */
+    destinationChain: string
+    /** Destination token symbol, contract address, or token key. */
     destinationToken: string
-    /** Funding method passed to provider preparation. */
+    /** Route method passed to provider preparation. */
     method: Transfer.Method
     /** Amount mode the caller selected. */
     mode: Transfer.Mode
-    /** Funding provider ID selected by the caller. */
+    /** Route provider ID selected by the caller. */
     provider?: string | undefined
-    /** Funding providers considered by the request. */
+    /** Route providers considered by the request. */
     providers: readonly Provider[]
     /** Source amount in base units. */
     sourceAmount: string
@@ -1399,15 +1707,17 @@ export declare namespace getPrepareCandidates {
   }
 }
 
-/** Source amount unit accepted by the funding quote request. */
+/** Source amount unit accepted by the route quote request. */
 export type SourceAmountUnits = z.output<typeof schema.SourceAmountUnits>
 
-/** Fetch implementation accepted by funding provider factories. */
+/** Fetch implementation accepted by route provider factories. */
 export type Fetch = typeof globalThis.fetch
 
 /** Returns bounded provider failure details suitable for structured request logs. */
 export function failure(options: ProviderFailure): failure.Result {
   const { cause, operation, provider } = options
+  const rpc = Viem.requestFailure(cause)
+  if (rpc) return { ...rpc, id: provider.id, operation }
   if (
     cause instanceof ProviderTimeoutError ||
     (cause instanceof DOMException && cause.name === 'AbortError')
@@ -1423,7 +1733,11 @@ export function failure(options: ProviderFailure): failure.Result {
       status: cause.status,
     }
   }
-  if (cause instanceof ProviderPayloadError)
+  if (
+    cause instanceof ProviderPayloadError ||
+    cause instanceof WebhookAuthenticationError ||
+    cause instanceof WebhookPayloadError
+  )
     return { failure: 'payload', id: provider.id, operation }
   if (cause instanceof ProviderRateLimitError)
     return { failure: 'rate_limit', id: provider.id, operation }
@@ -1434,12 +1748,16 @@ export function failure(options: ProviderFailure): failure.Result {
 export declare namespace failure {
   /** Bounded provider failure fields. */
   type Result = {
+    /** EIP-155 chain whose RPC request failed. */
+    chainId?: number | undefined
     /** Stable provider error code, when one is safe to retain. */
     code?: string | undefined
     /** Failure boundary that rejected the provider request. */
-    failure: 'http' | 'network' | 'payload' | 'rate_limit' | 'timeout' | 'unknown'
+    failure: 'http' | 'network' | 'payload' | 'query' | 'rate_limit' | 'timeout' | 'unknown'
     /** Provider identifier. */
     id: string
+    /** Upstream error message, when one was returned. */
+    message?: string | undefined
     /** Provider operation identifier. */
     operation: ProviderOperation
     /** Upstream HTTP status, when a response was received. */
@@ -1537,6 +1855,7 @@ async function quoteCandidate(
   options: {
     cache: CachePolicy
     provider: Provider
+    quotaKey: string
     request: QuoteRequest
     timeoutMs: number
   },
@@ -1550,6 +1869,7 @@ async function quoteCandidate(
             cache: options.cache,
             destinationChain: candidate.destinationChain,
             destinationToken: candidate.destinationToken,
+            quotaKey: options.quotaKey,
             request: options.request,
             route: candidate.route,
             sourceAmount: candidate.sourceAmount,
@@ -1688,8 +2008,8 @@ type SuccessfulQuoteResult = getQuote.ReturnType & {
   status: 'available' | 'thin'
 }
 
-function createQuote(candidate: QuoteCandidate, quote: SuccessfulQuoteResult): FundingQuote {
-  return schema.FundingQuote.parse({
+function createQuote(candidate: QuoteCandidate, quote: SuccessfulQuoteResult): RoutesQuote {
+  return schema.RoutesQuote.parse({
     destinationAmount: Value.tokenAmount({
       baseUnits: quote.destinationAmount,
       currency: candidate.destinationToken.currency,
@@ -1712,10 +2032,6 @@ function createQuote(candidate: QuoteCandidate, quote: SuccessfulQuoteResult): F
       ...(quote.quality?.estimatedSeconds !== undefined
         ? { estimatedSeconds: quote.quality.estimatedSeconds }
         : {}),
-      liquiditySource: quote.quality?.liquiditySource ?? 'providerQuote',
-      ...(quote.quality?.sourceDetail !== undefined
-        ? { sourceDetail: quote.quality.sourceDetail }
-        : {}),
       tier: quote.status === 'thin' ? ('thin' as const) : ('liquid' as const),
     },
     quote: {
@@ -1766,7 +2082,8 @@ function errorCode(input: unknown) {
   return parsed.success ? parsed.data : undefined
 }
 
-function attemptResult(attempt: ProviderAttempt): ProviderAttemptResult {
+/** Formats one provider attempt for logs and aggregate metrics. */
+export function formatAttempt(attempt: ProviderAttempt): ProviderAttemptResult {
   return {
     durationMs: attempt.durationMs,
     ...(attempt.outcome === 'failed'
@@ -1784,9 +2101,23 @@ function attemptResult(attempt: ProviderAttempt): ProviderAttemptResult {
   }
 }
 
-function resolveDestinationToken(input: string | undefined, catalog: core_Catalog.Snapshot) {
+function resolveDestinationChain(input: string, catalog: core_Catalog.Snapshot) {
+  const normalized = normalizeInput(input)
+  const chain = catalog.chainsByKey.get(normalized)
+  if (!chain || !catalog.routes.some((entry) => entry.route.destination.chain.id === chain.id))
+    throw new UnsupportedDestinationChainError()
+  return chain
+}
+
+function resolveDestinationToken(
+  chain: Chain,
+  input: string | undefined,
+  catalog: core_Catalog.Snapshot,
+) {
   const destinations = uniqueBy(
-    catalog.routes.map((entry) => entry.route.destination),
+    catalog.routes
+      .filter((entry) => entry.route.destination.chain.id === chain.id)
+      .map((entry) => entry.route.destination),
     (token) => `${token.chain.id}:${token.address}`,
   )
   if (input === undefined) {
@@ -1890,59 +2221,74 @@ function normalizeAccountAddress(value: string, chain: ChainRef): string | undef
   }
 }
 
+/** Error thrown when the caller supplies an unsupported destination chain. */
+export class UnsupportedDestinationChainError extends Error {
+  override name = 'RoutesProvider.UnsupportedDestinationChainError'
+}
+
 /** Error thrown when the caller supplies an unsupported destination token. */
 export class UnsupportedDestinationTokenError extends Error {
-  override name = 'FundingProvider.UnsupportedDestinationTokenError'
+  override name = 'RoutesProvider.UnsupportedDestinationTokenError'
 }
 
 /** Error thrown when a provider webhook cannot be authenticated. */
 export class WebhookAuthenticationError extends Error {
-  override name = 'FundingProvider.WebhookAuthenticationError'
+  override name = 'RoutesProvider.WebhookAuthenticationError'
 }
 
 /** Error thrown when an authenticated provider webhook has an invalid body. */
 export class WebhookPayloadError extends Error {
-  override name = 'FundingProvider.WebhookPayloadError'
+  override name = 'RoutesProvider.WebhookPayloadError'
 }
 
 /** Error thrown when the caller supplies an invalid source amount. */
 export class InvalidAmountError extends Error {
-  override name = 'FundingProvider.InvalidAmountError'
+  override name = 'RoutesProvider.InvalidAmountError'
 }
 
 /** Error thrown when the caller supplies an invalid source-chain refund address. */
 export class InvalidRefundAddressError extends Error {
-  override name = 'FundingProvider.InvalidRefundAddressError'
+  override name = 'RoutesProvider.InvalidRefundAddressError'
+}
+
+/** Error thrown when the caller supplies an invalid destination-chain recipient. */
+export class InvalidRecipientAddressError extends Error {
+  override name = 'RoutesProvider.InvalidRecipientAddressError'
+}
+
+/** Error thrown when the caller supplies an invalid source-chain sender. */
+export class InvalidSenderAddressError extends Error {
+  override name = 'RoutesProvider.InvalidSenderAddressError'
 }
 
 /** Error thrown when provider deployment configuration is invalid. */
 export class ProviderConfigurationError extends Error {
-  override name = 'FundingProvider.ProviderConfigurationError'
+  override name = 'RoutesProvider.ProviderConfigurationError'
 }
 
 /** Error thrown when a provider response does not match the requested quote. */
 export class ProviderPayloadError extends Error {
-  override name = 'FundingProvider.ProviderPayloadError'
+  override name = 'RoutesProvider.ProviderPayloadError'
 }
 
 /** Error thrown when a provider confirms that no executable route is available. */
 export class ProviderUnavailableError extends Error {
-  override name = 'FundingProvider.ProviderUnavailableError'
+  override name = 'RoutesProvider.ProviderUnavailableError'
 }
 
 /** Error thrown internally when a provider exceeds its quote timeout. */
 export class ProviderTimeoutError extends Error {
-  override name = 'FundingProvider.ProviderTimeoutError'
+  override name = 'RoutesProvider.ProviderTimeoutError'
 }
 
 /** Error thrown when an internal provider quota rejects a quote request. */
 export class ProviderRateLimitError extends Error {
-  override name = 'FundingProvider.ProviderRateLimitError'
+  override name = 'RoutesProvider.ProviderRateLimitError'
 }
 
 /** Error thrown when a provider returns an unsuccessful HTTP response. */
 export class ProviderResponseError extends Error {
-  override name = 'FundingProvider.ProviderResponseError'
+  override name = 'RoutesProvider.ProviderResponseError'
 
   constructor(
     /** Provider response status. */
@@ -1956,13 +2302,13 @@ export class ProviderResponseError extends Error {
 
 /** Error thrown when every matching provider fails to produce a quote. */
 export class ProviderQuoteError extends Error {
-  override name = 'FundingProvider.ProviderQuoteError'
+  override name = 'RoutesProvider.ProviderQuoteError'
 
   /** Provider failures that prevented a successful quote. */
   failures: readonly ProviderFailure[]
 
   /** Bounded provider attempts retained for request logs. */
-  fundingProviderAttempts: readonly ProviderAttemptResult[]
+  routesProviderAttempts: readonly ProviderAttemptResult[]
 
   /** First bounded provider failure retained for request logs. */
   providerFailure?: failure.Result | undefined
@@ -1973,7 +2319,7 @@ export class ProviderQuoteError extends Error {
   constructor(failures: readonly ProviderFailure[], attempts: readonly ProviderAttempt[] = []) {
     super()
     this.failures = failures
-    this.fundingProviderAttempts = attempts.map(attemptResult)
+    this.routesProviderAttempts = attempts.map(formatAttempt)
     const values = failures.map(failure)
     const first = values[0]
     if (first) this.providerFailure = first
@@ -1983,10 +2329,10 @@ export class ProviderQuoteError extends Error {
 
 /** Error thrown when the caller filters to an unknown provider. */
 export class UnsupportedProviderError extends Error {
-  override name = 'FundingProvider.UnsupportedProviderError'
+  override name = 'RoutesProvider.UnsupportedProviderError'
 }
 
 /** Error thrown when the caller supplies an unsupported source chain. */
 export class UnsupportedSourceChainError extends Error {
-  override name = 'FundingProvider.UnsupportedSourceChainError'
+  override name = 'RoutesProvider.UnsupportedSourceChainError'
 }