tapimo 0.13.0 → 0.15.0

package/dist/internal/{funding → routes}/Provider.js

@@ -4,10 +4,12 @@ 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';
-/** Tempo token used when the caller omits `destinationToken`. */
+import * as Economics from './Economics.js';
+/** Destination token used when the caller omits `destinationToken`. */
 const defaultDestinationToken = 'usdce';
-/** Funding provider schemas. */
+/** Route provider schemas. */
 export var schema;
 (function (schema) {
     /** Bounded upstream error code safe for structured logs. */
@@ -26,11 +28,11 @@ export var schema;
         errorType: z.optional(z.string()),
         type: z.optional(z.string()),
     });
-    /** Positive decimal amount accepted by funding quote requests. */
+    /** Positive decimal amount accepted by route quote requests. */
     schema.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. */
     schema.PositiveInteger = z.string().check(z.regex(/^(?=.*[1-9])\d+$/));
-    /** Normalized chain reference passed to funding providers. */
+    /** Normalized chain reference passed to route providers. */
     schema.ChainRef = OpenApi.component(Schema.describe(z.object({
         addressFormat: z
             .enum(['base58', 'base58check', 'hex'])
@@ -42,8 +44,8 @@ export var schema;
         name: z
             .string()
             .check(z.describe('Human-readable chain name.'), z.meta({ examples: ['Base'] })),
-    }), 'A normalized chain reference for funding quotes.'), 'FundingChain');
-    /** Normalized token reference passed to funding providers. */
+    }), 'A normalized chain reference for route quotes.'), 'RoutesChain');
+    /** Normalized token reference passed to route providers. */
     schema.TokenRef = OpenApi.component(Schema.describe(z.object({
         address: z
             .string()
@@ -68,43 +70,54 @@ export var schema;
         })),
         verified: z
             .boolean()
-            .check(z.describe('Whether Tempo recognizes this token in its funding quote inventory.'), z.meta({ examples: [true] })),
-    }), 'A normalized token reference for funding quotes.'), 'FundingToken');
-    /** Provider identity embedded in funding resources. */
+            .check(z.describe('Whether Tempo recognizes this token in its route quote inventory.'), z.meta({ examples: [true] })),
+    }), 'A normalized token reference for route quotes.'), 'RoutesToken');
+    /** Provider identity embedded in route resources. */
     schema.ProviderRef = OpenApi.component(Schema.describe(z.object({
         id: z.string().check(z.describe('Stable provider id.'), z.meta({ examples: ['relay'] })),
         name: z
             .string()
             .check(z.describe('Human-readable provider name.'), z.meta({ examples: ['Relay'] })),
-    }), 'Provider metadata embedded in a funding quote.'), 'FundingProvider');
-    /** Source amount unit accepted by a funding quote request. */
+    }), 'Provider metadata embedded in a route quote.'), 'RoutesProvider');
+    /** One token amount paid by a subsidy provider. */
+    schema.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: schema.TokenRef,
+    }), 'One token amount paid on behalf of the deposit recipient.'), 'RoutesSubsidy');
+    /** Source amount unit accepted by a route quote request. */
     schema.SourceAmountUnits = z
         ._default(z.enum(['baseUnits', 'decimal']), 'baseUnits')
         .check(z.describe('Whether `sourceAmount` is base units or a human-readable decimal.'), z.meta({ examples: ['baseUnits', 'decimal'] }));
-    /** Normalized caller request passed to funding providers. */
+    /** Normalized caller request passed to route providers. */
     schema.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'] })),
+            .check(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.'), z.meta({ examples: ['relay'] })),
+            .check(z.describe('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', 'stargate'] })),
         sourceAmount: schema.PositiveDecimal.check(z.describe('Positive source token amount. Base units by default, so 1 USDC is `1000000`.'), z.meta({ examples: ['1000000'] })),
         sourceAmountUnits: schema.SourceAmountUnits,
         sourceChain: z
             .string()
-            .check(z.minLength(1), z.describe('Source chain alias or stable id, such as `base`, `solana`, or `eip155:8453`.'), z.meta({ examples: ['base', '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'] })),
+            .check(z.minLength(1), z.describe('Source chain alias or stable id, such as `base`, `solana`, or `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', '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. */
     schema.QuoteStatus = z.enum(['available', 'thin', 'unknown', 'unavailable']);
     /** Machine-readable provider quote quality tier. */
     schema.QualityTier = z.enum(['liquid', 'thin', 'unknown', 'unavailable']);
-    /** Quote data returned by a funding provider. */
+    /** Quote data returned by a route provider. */
     schema.GetQuoteResult = Schema.describe(z.object({
         expiresAt: z.optional(z.iso.datetime()),
         destinationAmountMin: z.optional(Schema.DecimalString),
@@ -117,8 +130,8 @@ export var schema;
         })),
         sampledAt: z.iso.datetime(),
         status: schema.QuoteStatus,
-    }), 'Quote data returned by a funding provider.');
-    /** Executable preparation returned by a funding provider. */
+    }), 'Quote data returned by a route provider.');
+    /** Executable preparation returned by a route provider. */
     schema.PrepareResult = z.object({
         action: Action.schema.Action,
         correlation: z.optional(z.object({
@@ -133,10 +146,11 @@ export var schema;
             side: z.enum(['destination', 'source']),
             token: z.optional(schema.TokenRef),
         })),
+        providerState: z.optional(z.record(z.string(), z.unknown())),
         quality: schema.GetQuoteResult.shape.quality,
         sampledAt: z.iso.datetime(),
     });
-    /** Reusable deposit address provisioned by a funding provider. */
+    /** Reusable deposit address provisioned by a route provider. */
     schema.DepositAddressResult = z
         .object({
         address: z
@@ -168,6 +182,7 @@ export var schema;
         refundAmountExpected: z.optional(z.string().check(z.regex(/^\d+$/))),
         refundTransactionHashes: z.array(z.string()),
         sourceTransactionHashes: z.array(z.string()),
+        subsidy: z.optional(schema.Subsidy),
         status: z.string().check(z.minLength(1)),
         updatedAt: z.iso.datetime(),
     });
@@ -176,22 +191,16 @@ export var schema;
         continuation: z.optional(z.string().check(z.minLength(1))),
         requests: z.array(schema.DepositAddressRequest),
     });
-    /** Quote quality signals exposed to funding API callers. */
-    schema.FundingQuoteQuality = OpenApi.component(Schema.describe(z.object({
+    /** Quote quality signals exposed to routes API callers. */
+    schema.RoutesQuoteQuality = OpenApi.component(Schema.describe(z.object({
         estimatedSeconds: z
             .optional(z.number().check(z.int(), z.nonnegative()))
             .check(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(z.describe('Machine-readable quote quality tier for a successful quote.'), z.meta({ examples: ['liquid'] })),
-    }), 'Machine-readable liquidity, fee, and source signals for a successful quote.'), 'FundingQuoteQuality');
-    /** Provider quote freshness data exposed to funding API callers. */
+    }), 'Machine-readable quality and settlement-time signals for a successful quote.'), 'RoutesQuoteQuality');
+    /** Provider quote freshness data exposed to routes API callers. */
     schema.QuoteDetails = OpenApi.component(Schema.describe(z.object({
         expiresAt: z
             .optional(z.iso.datetime())
@@ -199,56 +208,97 @@ export var schema;
         sampledAt: z.iso
             .datetime()
             .check(z.describe('Timestamp for the live quote request.'), z.meta({ examples: ['2026-01-01T00:00:00Z'] })),
-    }), 'Freshness data for a provider funding quote.'), 'FundingQuoteDetails');
-    /** Successful normalized funding quote returned to callers. */
-    schema.FundingQuote = OpenApi.component(Schema.describe(z.object({
-        destinationAmount: Schema.TokenAmount.check(z.describe('Expected destination amount.')),
+    }), 'Freshness data for a provider route quote.'), 'RoutesQuoteDetails');
+    /** Successful normalized route quote returned to callers. */
+    schema.RoutesQuote = OpenApi.component(Schema.describe(z.object({
+        destinationAmount: Schema.TokenAmount.check(z.describe('Expected amount received after provider deductions, including pool fees.')),
         destinationAmountMin: z
             .optional(Schema.TokenAmount)
             .check(z.describe('Provider-derived minimum destination amount. Symbiosis and Squid quotes use a fixed 1% slippage tolerance.')),
-        destinationChain: schema.ChainRef.check(z.describe('Destination chain, always Tempo mainnet in V1.')),
-        destinationToken: schema.TokenRef.check(z.describe('Tempo token expected from this quote.')),
+        destinationChain: schema.ChainRef.check(z.describe('Chain that receives the routed token.')),
+        destinationToken: schema.TokenRef.check(z.describe('Token expected from this quote.')),
         id: z
             .string()
-            .check(z.describe('Stable deterministic funding quote id.'), z.meta({ examples: ['base-usdc-tempo-usdce-relay'] })),
+            .check(z.describe('Stable deterministic route quote id.'), z.meta({ examples: ['base-usdc-tempo-usdce-relay'] })),
         provider: schema.ProviderRef,
-        quality: schema.FundingQuoteQuality,
+        quality: schema.RoutesQuoteQuality,
         quote: schema.QuoteDetails,
         sourceAmount: Schema.TokenAmount,
         sourceChain: schema.ChainRef.check(z.describe('Chain where the caller currently holds funds.')),
         sourceToken: schema.TokenRef.check(z.describe('Token the caller currently holds.')),
-    }), 'One successful provider-specific funding quote.'), 'FundingQuote');
+    }), 'One successful provider-specific route quote.'), 'RoutesQuote');
 })(schema || (schema = {}));
-/** Defines a funding provider from its identity and quote implementation. */
+/** Defines a route provider from its identity and quote implementation. */
 export function from(options) {
     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' });
 }
-/** Narrows a registered provider to a funding provider. */
+/** Narrows a registered provider to a route provider. */
 export function is(provider) {
-    return (provider.type === 'funding' && 'getQuote' in provider && typeof provider.getQuote === 'function');
+    return (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) {
     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) {
     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) {
     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) {
     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) {
+    return (typeof provider.verifyDestinationDelivery === 'function' &&
+        typeof provider.verifySourceTransaction === 'function');
+}
+/** Narrows a route provider to one that verifies submitted source transactions. */
+export function canVerifySourceTransaction(provider) {
+    return typeof provider.verifySourceTransaction === 'function';
+}
+/** Narrows a route provider to one with authenticated webhook receipt. */
 export function canReceiveWebhook(provider) {
     return provider.webhook !== undefined;
 }
+/** Observes one provider operation without changing its result. */
+export async function observe(provider, fn, options) {
+    const start = performance.now();
+    const report = (attempt) => {
+        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;
+    }
+}
 // Slow provider responses can still contain valid quotes; keep the boundary
 // above observed Relay latency while bounding the total request duration.
 const defaultQuoteTimeoutMs = 5_000;
@@ -270,13 +320,13 @@ export function getChains(options) {
         ];
     });
 }
-/** Returns the supplied funding quote providers. */
+/** Returns the supplied route quote providers. */
 export function getProviders(options) {
     return options.providers
         .filter((provider) => (options.catalog.routesByProvider.get(provider.id)?.length ?? 0) > 0)
         .map((provider) => schema.ProviderRef.parse(provider));
 }
-/** Returns successful live funding quotes from the supplied providers. */
+/** Returns successful live route quotes from the supplied providers. */
 export async function getQuotes(options) {
     const providers = options.providers ?? [];
     const operation = 'getQuote';
@@ -291,7 +341,9 @@ export async function 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,
@@ -329,7 +381,7 @@ export async function getQuotes(options) {
             options.onAttempt?.(attempt);
         }
         catch {
-            // Observability hooks never alter funding quote behavior.
+            // Observability hooks never alter route quote behavior.
         }
     }
     const quotes = results.flatMap((result) => result.status === 'fulfilled' && result.value ? [result.value] : []);
@@ -342,6 +394,41 @@ export async function 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;
@@ -354,7 +441,8 @@ export function getQuoteCandidates(options) {
         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 [];
@@ -392,23 +480,16 @@ export async function createDepositAddress(options) {
     const operation = 'createDepositAddress';
     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 {
         const parsed = schema.DepositAddressResult.safeParse(await withTimeout((signal) => selected.provider.createDepositAddress({
             amount: options.amount,
             candidate: selected.candidate,
-            recipient,
-            refundAddress,
+            recipient: selected.recipient,
+            refundAddress: selected.refundAddress,
             subsidize: options.subsidize,
         }, signal), options.providerTimeoutMs ?? defaultPrepareTimeoutMs));
         if (!parsed.success)
@@ -432,7 +513,7 @@ export async function createDepositAddress(options) {
         catch {
             // Observability hooks never alter provisioning behavior.
         }
-        return { ...selected, recipient, refundAddress, result };
+        return { ...selected, result };
     }
     catch (cause) {
         const attempt = cause instanceof ProviderUnavailableError
@@ -460,6 +541,20 @@ export async function createDepositAddress(options) {
         throw new ProviderQuoteError([{ cause, operation, provider: selected.provider }], [attempt]);
     }
 }
+/** Selects and normalizes the deterministic reusable-address route without provisioning it. */
+export function selectDepositAddress(options) {
+    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 };
+}
 /**
  * Prepares one executable transfer across capability-enabled candidates,
  * selecting the best successful preparation. Returns `undefined` when no
@@ -471,6 +566,13 @@ export async function prepareTransfer(options) {
     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 = [];
     const results = await Promise.allSettled(candidates.map(async ({ candidate, provider }) => {
         const start = performance.now();
@@ -479,8 +581,8 @@ export async function prepareTransfer(options) {
                 candidate,
                 method: options.method,
                 mode: options.mode,
-                recipient: options.recipient,
-                sender: options.sender,
+                recipient,
+                sender,
                 slippageBps: options.slippageBps,
             };
             const parsed = schema.PrepareResult.safeParse(await withTimeout((signal) => provider.prepareTransfer(parameters, signal), options.providerTimeoutMs ?? defaultPrepareTimeoutMs));
@@ -507,12 +609,14 @@ export async function prepareTransfer(options) {
                     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) {
@@ -578,7 +682,15 @@ export async function prepareTransfer(options) {
             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,
+    };
 }
 /**
  * Returns capability-enabled reusable-address candidates for a route. Tokens
@@ -623,14 +735,14 @@ export function getPrepareCandidates(options) {
     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)
+        if (entry.route.destination.chain.id !== destinationChain.id)
             return [];
         if (!matchesToken(entry.route.source, options.sourceToken))
             return [];
@@ -663,6 +775,9 @@ export function getPrepareCandidates(options) {
 /** Returns bounded provider failure details suitable for structured request logs. */
 export function failure(options) {
     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'))
         return { failure: 'timeout', id: provider.id, operation };
@@ -676,7 +791,9 @@ export function failure(options) {
             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 };
@@ -747,6 +864,7 @@ async function quoteCandidate(candidate, options) {
         cache: options.cache,
         destinationChain: candidate.destinationChain,
         destinationToken: candidate.destinationToken,
+        quotaKey: options.quotaKey,
         request: options.request,
         route: candidate.route,
         sourceAmount: candidate.sourceAmount,
@@ -850,7 +968,7 @@ function parseDecimalUnits(value, decimals) {
     }
 }
 function createQuote(candidate, quote) {
-    return schema.FundingQuote.parse({
+    return schema.RoutesQuote.parse({
         destinationAmount: Value.tokenAmount({
             baseUnits: quote.destinationAmount,
             currency: candidate.destinationToken.currency,
@@ -873,10 +991,6 @@ function createQuote(candidate, quote) {
             ...(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' : 'liquid',
         },
         quote: {
@@ -924,7 +1038,8 @@ function errorCode(input) {
     const parsed = schema.ErrorCode.safeParse(code);
     return parsed.success ? parsed.data : undefined;
 }
-function attemptResult(attempt) {
+/** Formats one provider attempt for logs and aggregate metrics. */
+export function formatAttempt(attempt) {
     return {
         durationMs: attempt.durationMs,
         ...(attempt.outcome === 'failed'
@@ -941,8 +1056,17 @@ function attemptResult(attempt) {
         outcome: attempt.outcome,
     };
 }
-function resolveDestinationToken(input, catalog) {
-    const destinations = uniqueBy(catalog.routes.map((entry) => entry.route.destination), (token) => `${token.chain.id}:${token.address}`);
+function resolveDestinationChain(input, catalog) {
+    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, input, catalog) {
+    const destinations = uniqueBy(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) {
         const destination = destinations.find((candidate) => candidate.slug === defaultDestinationToken);
         if (!destination)
@@ -1023,51 +1147,63 @@ function normalizeAccountAddress(value, chain) {
         return undefined;
     }
 }
+/** Error thrown when the caller supplies an unsupported destination chain. */
+export class UnsupportedDestinationChainError extends Error {
+    name = 'RoutesProvider.UnsupportedDestinationChainError';
+}
 /** Error thrown when the caller supplies an unsupported destination token. */
 export class UnsupportedDestinationTokenError extends Error {
-    name = 'FundingProvider.UnsupportedDestinationTokenError';
+    name = 'RoutesProvider.UnsupportedDestinationTokenError';
 }
 /** Error thrown when a provider webhook cannot be authenticated. */
 export class WebhookAuthenticationError extends Error {
-    name = 'FundingProvider.WebhookAuthenticationError';
+    name = 'RoutesProvider.WebhookAuthenticationError';
 }
 /** Error thrown when an authenticated provider webhook has an invalid body. */
 export class WebhookPayloadError extends Error {
-    name = 'FundingProvider.WebhookPayloadError';
+    name = 'RoutesProvider.WebhookPayloadError';
 }
 /** Error thrown when the caller supplies an invalid source amount. */
 export class InvalidAmountError extends Error {
-    name = 'FundingProvider.InvalidAmountError';
+    name = 'RoutesProvider.InvalidAmountError';
 }
 /** Error thrown when the caller supplies an invalid source-chain refund address. */
 export class InvalidRefundAddressError extends Error {
-    name = 'FundingProvider.InvalidRefundAddressError';
+    name = 'RoutesProvider.InvalidRefundAddressError';
+}
+/** Error thrown when the caller supplies an invalid destination-chain recipient. */
+export class InvalidRecipientAddressError extends Error {
+    name = 'RoutesProvider.InvalidRecipientAddressError';
+}
+/** Error thrown when the caller supplies an invalid source-chain sender. */
+export class InvalidSenderAddressError extends Error {
+    name = 'RoutesProvider.InvalidSenderAddressError';
 }
 /** Error thrown when provider deployment configuration is invalid. */
 export class ProviderConfigurationError extends Error {
-    name = 'FundingProvider.ProviderConfigurationError';
+    name = 'RoutesProvider.ProviderConfigurationError';
 }
 /** Error thrown when a provider response does not match the requested quote. */
 export class ProviderPayloadError extends Error {
-    name = 'FundingProvider.ProviderPayloadError';
+    name = 'RoutesProvider.ProviderPayloadError';
 }
 /** Error thrown when a provider confirms that no executable route is available. */
 export class ProviderUnavailableError extends Error {
-    name = 'FundingProvider.ProviderUnavailableError';
+    name = 'RoutesProvider.ProviderUnavailableError';
 }
 /** Error thrown internally when a provider exceeds its quote timeout. */
 export class ProviderTimeoutError extends Error {
-    name = 'FundingProvider.ProviderTimeoutError';
+    name = 'RoutesProvider.ProviderTimeoutError';
 }
 /** Error thrown when an internal provider quota rejects a quote request. */
 export class ProviderRateLimitError extends Error {
-    name = 'FundingProvider.ProviderRateLimitError';
+    name = 'RoutesProvider.ProviderRateLimitError';
 }
 /** Error thrown when a provider returns an unsuccessful HTTP response. */
 export class ProviderResponseError extends Error {
     status;
     body;
-    name = 'FundingProvider.ProviderResponseError';
+    name = 'RoutesProvider.ProviderResponseError';
     constructor(
     /** Provider response status. */
     status, 
@@ -1080,11 +1216,11 @@ export class ProviderResponseError extends Error {
 }
 /** Error thrown when every matching provider fails to produce a quote. */
 export class ProviderQuoteError extends Error {
-    name = 'FundingProvider.ProviderQuoteError';
+    name = 'RoutesProvider.ProviderQuoteError';
     /** Provider failures that prevented a successful quote. */
     failures;
     /** Bounded provider attempts retained for request logs. */
-    fundingProviderAttempts;
+    routesProviderAttempts;
     /** First bounded provider failure retained for request logs. */
     providerFailure;
     /** Bounded provider failures retained when multiple providers failed. */
@@ -1092,7 +1228,7 @@ export class ProviderQuoteError extends Error {
     constructor(failures, attempts = []) {
         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)
@@ -1103,10 +1239,10 @@ export class ProviderQuoteError extends Error {
 }
 /** Error thrown when the caller filters to an unknown provider. */
 export class UnsupportedProviderError extends Error {
-    name = 'FundingProvider.UnsupportedProviderError';
+    name = 'RoutesProvider.UnsupportedProviderError';
 }
 /** Error thrown when the caller supplies an unsupported source chain. */
 export class UnsupportedSourceChainError extends Error {
-    name = 'FundingProvider.UnsupportedSourceChainError';
+    name = 'RoutesProvider.UnsupportedSourceChainError';
 }
 //# sourceMappingURL=Provider.js.map