tapimo 0.7.1 → 0.7.2

package/dist/internal/funding/Provider.js

@@ -0,0 +1,1081 @@
+import { Address, Base58, Bytes, Hash, Value as core_Value } from 'ox';
+import * as z from 'zod/mini';
+import * as core_Provider from '../Provider.js';
+import * as Schema from '../Schema.js';
+import * as Value from '../Value.js';
+import * as Action from './Action.js';
+/** Tempo token used when the caller omits `destinationToken`. */
+const defaultDestinationToken = 'usdce';
+/** Funding provider schemas. */
+export var schema;
+(function (schema) {
+    /** Bounded upstream error code safe for structured logs. */
+    schema.ErrorCode = z.string().check(z.regex(/^[A-Za-z0-9_.:-]{1,64}$/));
+    /** Nested upstream error fields used to extract a stable code. */
+    schema.Error = z.object({
+        code: z.optional(z.string()),
+        type: z.optional(z.string()),
+    });
+    /** Common upstream error body fields used to extract a stable code. */
+    schema.ErrorBody = z.object({
+        _tag: z.optional(z.string()),
+        code: z.optional(z.string()),
+        error: z.optional(schema.Error),
+        errorCode: z.optional(z.string()),
+        errorType: z.optional(z.string()),
+        type: z.optional(z.string()),
+    });
+    /** Positive decimal amount accepted by funding quote requests. */
+    schema.PositiveDecimal = z.string().check(z.regex(/^(?=.*[1-9])\d+(\.\d+)?$/));
+    /** Positive base-unit amount accepted by funding quote requests. */
+    schema.PositiveInteger = z.string().check(z.regex(/^(?=.*[1-9])\d+$/));
+    /** Normalized chain reference passed to funding providers. */
+    schema.ChainRef = Schema.describe(z.object({
+        addressFormat: z
+            .enum(['base58', 'base58check', 'hex'])
+            .check(z.describe('Address encoding used by accounts and token identifiers on this chain.'), z.meta({ examples: ['hex'] })),
+        id: z.string().check(z.describe('CAIP-2 chain id.'), z.meta({ examples: ['eip155:8453'] })),
+        kind: z
+            .enum(['evm', 'solana', 'tron'])
+            .check(z.describe('Chain execution family used for provider routing.'), z.meta({ examples: ['evm'] })),
+        name: z
+            .string()
+            .check(z.describe('Human-readable chain name.'), z.meta({ examples: ['Base'] })),
+    }), 'A normalized chain reference for funding quotes.');
+    /** Normalized token reference passed to funding providers. */
+    schema.TokenRef = Schema.describe(z.object({
+        address: z
+            .string()
+            .check(z.describe('Contract address, mint, or issuer address on the token chain.'), z.meta({ examples: ['0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'] })),
+        currency: z
+            .string()
+            .check(z.describe('Monetary denomination represented by this token.'), z.meta({ examples: ['USD'] })),
+        decimals: z
+            .number()
+            .check(z.int(), z.gte(0), z.describe('Number of decimal places this token uses.'), z.meta({ examples: [6] })),
+        name: z
+            .string()
+            .check(z.describe('Human-readable token name.'), z.meta({ examples: ['USD Coin'] })),
+        standard: z
+            .string()
+            .check(z.describe('Token standard on the token chain.'), z.meta({ examples: ['ERC-20'] })),
+        symbol: z
+            .string()
+            .check(z.describe('Short token ticker symbol.'), z.meta({ examples: ['USDC'] })),
+        tokenKey: z.string().check(z.describe('Stable Tempo token key scoped to the token chain.'), z.meta({
+            examples: ['eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'],
+        })),
+        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.');
+    /** Provider identity embedded in funding resources. */
+    schema.ProviderRef = 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.');
+    /** Source amount unit accepted by a funding 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. */
+    schema.QuoteRequest = z
+        .strictObject({
+        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'] })),
+        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'] })),
+        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.describe('Query parameters for live funding quotes into Tempo.'));
+    /** 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. */
+    schema.GetQuoteResult = Schema.describe(z.object({
+        expiresAt: z.optional(z.iso.datetime()),
+        destinationAmountMin: z.optional(Schema.DecimalString),
+        destinationAmount: z.optional(Schema.DecimalString),
+        quality: z.optional(z.object({
+            estimatedSeconds: z.optional(z.number().check(z.int(), z.nonnegative())),
+            liquiditySource: z.string(),
+            sourceDetail: z.optional(z.string()),
+            tier: z.optional(schema.QualityTier),
+        })),
+        sampledAt: z.iso.datetime(),
+        status: schema.QuoteStatus,
+    }), 'Quote data returned by a funding provider.');
+    /** Executable preparation returned by a funding provider. */
+    schema.PrepareResult = z.object({
+        action: Action.schema.Action,
+        correlation: z.object({
+            checkEndpoint: z.optional(z.string()),
+            requestId: z.string().check(z.minLength(1)),
+        }),
+        destinationAmount: schema.PositiveInteger,
+        destinationAmountMin: schema.PositiveInteger,
+        expiresAt: z.optional(z.iso.datetime()),
+        fees: z.array(z.object({
+            amount: Schema.DecimalString,
+            side: z.enum(['destination', 'source']),
+        })),
+        quality: schema.GetQuoteResult.shape.quality,
+        sampledAt: z.iso.datetime(),
+    });
+    /** Reusable deposit address provisioned by a funding provider. */
+    schema.DepositAddressResult = z
+        .object({
+        address: z
+            .string()
+            .check(z.minLength(1), z.describe('Reusable source-chain deposit address.')),
+        correlation: z
+            .object({
+            checkEndpoint: z
+                .optional(z.string())
+                .check(z.describe('Provider status endpoint for the original address request.')),
+            requestId: z
+                .string()
+                .check(z.minLength(1), z.describe('Provider-issued address request identifier.')),
+        })
+            .check(z.describe('Private provider correlation retained for reconciliation.')),
+        destinationAmount: schema.PositiveInteger,
+        destinationAmountMin: schema.PositiveInteger,
+        expiresAt: z.optional(z.iso.datetime()),
+        fees: schema.PrepareResult.shape.fees,
+        sampledAt: z.iso.datetime(),
+    })
+        .check(z.describe('Reusable deposit address and quoted delivery terms returned by a provider.'));
+    /** One provider request discovered for a reusable deposit address. */
+    schema.DepositAddressRequest = z.object({
+        createdAt: z.iso.datetime(),
+        destinationTransactionHashes: z.array(z.string()),
+        id: z.string().check(z.minLength(1)),
+        sourceTransactionHashes: z.array(z.string()),
+        status: z.string().check(z.minLength(1)),
+        updatedAt: z.iso.datetime(),
+    });
+    /** One page of provider requests discovered for a reusable address. */
+    schema.DepositAddressRequestsResult = z.object({
+        continuation: z.optional(z.string().check(z.minLength(1))),
+        requests: z.array(schema.DepositAddressRequest),
+    });
+    /** Quote quality signals exposed to funding API callers. */
+    schema.FundingQuoteQuality = 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.');
+    /** Provider quote freshness data exposed to funding API callers. */
+    schema.QuoteDetails = Schema.describe(z.object({
+        expiresAt: z
+            .optional(z.iso.datetime())
+            .check(z.describe('Timestamp after which the provider quote is no longer valid.'), z.meta({ examples: ['2026-01-01T00:01:00Z'] })),
+        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.');
+    /** Successful normalized funding quote returned to callers. */
+    schema.FundingQuote = Schema.describe(z.object({
+        destinationAmount: Schema.TokenAmount.check(z.describe('Expected destination amount.')),
+        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.')),
+        id: z
+            .string()
+            .check(z.describe('Stable deterministic funding quote id.'), z.meta({ examples: ['base-usdc-tempo-usdce-relay'] })),
+        provider: schema.ProviderRef,
+        quality: schema.FundingQuoteQuality,
+        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.');
+})(schema || (schema = {}));
+/** Defines a funding 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' });
+}
+/** Narrows a registered provider to a funding provider. */
+export function is(provider) {
+    return (provider.type === 'funding' && 'getQuote' in provider && typeof provider.getQuote === 'function');
+}
+/** Narrows a funding 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. */
+export function canCreateDepositAddress(provider) {
+    return typeof provider.createDepositAddress === 'function';
+}
+/** Narrows a funding provider to one that tracks reusable deposit addresses. */
+export function canListDepositAddressRequests(provider) {
+    return typeof provider.listDepositAddressRequests === 'function';
+}
+/** Narrows a funding provider to one with authenticated webhook receipt. */
+export function canReceiveWebhook(provider) {
+    return provider.webhook !== undefined;
+}
+const defaultTimeoutMs = 2_000;
+/** Returns normalized chains and source tokens supported by quote providers. */
+export function getChains(options) {
+    const routes = getRoutes(options.catalog, options.providers);
+    const chains = uniqueBy(routes.map((entry) => entry.route.source.chain), (chain) => chain.id);
+    return chains.flatMap((chain) => {
+        const tokens = routes
+            .filter((entry) => entry.route.source.chain.id === chain.id)
+            .map((entry) => entry.route.source);
+        if (tokens.length === 0)
+            return [];
+        return [
+            {
+                ...chainRef(chain),
+                tokens: uniqueBy(tokens, (token) => token.address).map(tokenRef),
+            },
+        ];
+    });
+}
+/** Returns the supplied funding 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. */
+export async function getQuotes(options) {
+    const providers = options.providers ?? [];
+    const operation = 'getQuote';
+    const candidates = getQuoteCandidates(options).flatMap((candidate) => {
+        const provider = providers.find((entry) => entry.id === candidate.provider.id);
+        return provider ? [{ candidate, provider }] : [];
+    });
+    const attempts = new Map();
+    const results = await Promise.allSettled(candidates.map(async ({ candidate, provider }, index) => {
+        const start = performance.now();
+        try {
+            const result = await quoteCandidate(candidate, {
+                cache: options.cache ?? { bypass: false },
+                provider,
+                request: {
+                    destinationToken: options.destinationToken,
+                    provider: options.provider,
+                    sourceAmount: options.sourceAmount,
+                    sourceAmountUnits: options.sourceAmountUnits,
+                    sourceChain: options.sourceChain,
+                    sourceToken: options.sourceToken,
+                },
+                timeoutMs: options.providerTimeoutMs ?? defaultTimeoutMs,
+            });
+            attempts.set(index, {
+                durationMs: performance.now() - start,
+                operation,
+                outcome: result.outcome,
+                provider,
+            });
+            return 'quote' in result ? result.quote : undefined;
+        }
+        catch (cause) {
+            attempts.set(index, {
+                cause,
+                durationMs: performance.now() - start,
+                operation,
+                outcome: 'failed',
+                provider,
+            });
+            throw cause;
+        }
+    }));
+    const values = [...candidates.keys()].flatMap((index) => {
+        const attempt = attempts.get(index);
+        return attempt ? [attempt] : [];
+    });
+    for (const attempt of values) {
+        try {
+            options.onAttempt?.(attempt);
+        }
+        catch {
+            // Observability hooks never alter funding quote behavior.
+        }
+    }
+    const quotes = results.flatMap((result) => result.status === 'fulfilled' && result.value ? [result.value] : []);
+    const failures = results.flatMap((result, index) => result.status === 'rejected'
+        ? [
+            {
+                cause: result.reason,
+                operation,
+                provider: candidates[index].provider,
+            },
+        ]
+        : []);
+    if (quotes.length === 0 && failures.length > 0)
+        throw new ProviderQuoteError(failures, values);
+    return quotes;
+}
+/** Returns internal quote candidates for a normalized caller request. */
+export function getQuoteCandidates(options) {
+    const { catalog, providers } = options;
+    const amount = (options.sourceAmountUnits === 'baseUnits' ? schema.PositiveInteger : schema.PositiveDecimal).safeParse(options.sourceAmount);
+    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 provider = options.provider ? resolveProvider(options.provider, providers) : undefined;
+    if (providers.length === 0)
+        return [];
+    if (!sourceToken)
+        return [];
+    const sourceAmount = resolveSourceAmount({
+        amount: options.sourceAmount,
+        token: sourceToken,
+        units: options.sourceAmountUnits,
+    });
+    return getRoutes(catalog, providers)
+        .filter((entry) => entry.route.source.chain.id === sourceChain.id)
+        .filter((entry) => entry.route.source.address === sourceToken.address)
+        .filter((entry) => entry.route.destination.chain.id === destination.chain.id)
+        .filter((entry) => entry.route.destination.address === destination.address)
+        .filter((entry) => provider === undefined || entry.provider.id === provider.id)
+        .map((entry) => createQuoteCandidate({
+        destinationToken: entry.route.destination,
+        provider: entry.provider,
+        route: entry.route,
+        sourceAmount,
+        sourceToken: entry.route.source,
+    }));
+}
+const defaultPrepareTimeoutMs = 10_000;
+// Providers that return no quote validity window get a conservative default:
+// the caller must sign and submit promptly, mirroring wallet quote UX.
+const defaultQuoteTtlMs = 60_000;
+/**
+ * Provisions one reusable deposit address through the first deterministic
+ * capability-enabled provider. Returns `undefined` when no route is enabled.
+ */
+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];
+    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,
+            subsidize: options.subsidize,
+        }, signal), options.providerTimeoutMs ?? defaultPrepareTimeoutMs));
+        if (!parsed.success)
+            throw new ProviderPayloadError();
+        const result = parsed.data;
+        if (!normalizeAccountAddress(result.address, selected.candidate.sourceChain))
+            throw new ProviderPayloadError();
+        if (BigInt(result.destinationAmountMin) > BigInt(result.destinationAmount))
+            throw new ProviderPayloadError();
+        if (result.expiresAt !== undefined && Date.parse(result.expiresAt) <= Date.now())
+            throw new ProviderPayloadError();
+        const attempt = {
+            durationMs: performance.now() - start,
+            operation,
+            outcome: 'available',
+            provider: selected.provider,
+        };
+        try {
+            options.onAttempt?.(attempt);
+        }
+        catch {
+            // Observability hooks never alter provisioning behavior.
+        }
+        return { ...selected, recipient, refundAddress, result };
+    }
+    catch (cause) {
+        const attempt = cause instanceof ProviderUnavailableError
+            ? {
+                durationMs: performance.now() - start,
+                operation,
+                outcome: 'unavailable',
+                provider: selected.provider,
+            }
+            : {
+                cause,
+                durationMs: performance.now() - start,
+                operation,
+                outcome: 'failed',
+                provider: selected.provider,
+            };
+        try {
+            options.onAttempt?.(attempt);
+        }
+        catch {
+            // Observability hooks never alter provisioning behavior.
+        }
+        if (cause instanceof ProviderUnavailableError)
+            return undefined;
+        throw new ProviderQuoteError([{ cause, operation, provider: selected.provider }], [attempt]);
+    }
+}
+/**
+ * Prepares one executable transfer across capability-enabled candidates,
+ * selecting the best successful preparation. Returns `undefined` when no
+ * enabled corridor matches; throws {@link ProviderQuoteError} when every
+ * matching provider failed unexpectedly.
+ */
+export async function prepareTransfer(options) {
+    const operation = 'prepareTransfer';
+    const candidates = getPrepareCandidates(options);
+    if (candidates.length === 0)
+        return undefined;
+    const attempts = [];
+    const results = await Promise.allSettled(candidates.map(async ({ candidate, provider }) => {
+        const start = performance.now();
+        try {
+            const parsed = schema.PrepareResult.safeParse(await withTimeout((signal) => provider.prepareTransfer({
+                candidate,
+                method: options.method,
+                mode: options.mode,
+                recipient: options.recipient,
+                sender: options.sender,
+                slippageBps: options.slippageBps,
+            }, signal), options.providerTimeoutMs ?? defaultPrepareTimeoutMs));
+            if (!parsed.success)
+                throw new ProviderPayloadError();
+            const result = parsed.data;
+            const expiresAt = result.expiresAt ??
+                new Date(Date.parse(result.sampledAt) + defaultQuoteTtlMs).toISOString();
+            if (Date.parse(expiresAt) <= Date.now())
+                throw new ProviderPayloadError();
+            if (BigInt(result.destinationAmountMin) > BigInt(result.destinationAmount))
+                throw new ProviderPayloadError();
+            // A provider that ignores the caller's slippage bound is unusable for
+            // this request; enforce the bound against the quoted minimum.
+            if (options.slippageBps !== undefined) {
+                const basisPointScale = 10000n;
+                const numerator = BigInt(result.destinationAmount) * BigInt(10_000 - options.slippageBps);
+                const floor = (numerator + basisPointScale - 1n) / basisPointScale;
+                if (BigInt(result.destinationAmountMin) < floor)
+                    throw new ProviderPayloadError();
+            }
+            if (result.action.type === 'evm:calls')
+                try {
+                    Action.validateEvmCalls({
+                        action: result.action,
+                        sourceAmount: candidate.sourceAmount.amount,
+                        sourceTokenAddress: candidate.sourceToken.address,
+                    });
+                }
+                catch (cause) {
+                    if (cause instanceof Action.InvalidActionError)
+                        throw new ProviderPayloadError();
+                    throw cause;
+                }
+            attempts.push({
+                durationMs: performance.now() - start,
+                operation,
+                outcome: 'available',
+                provider,
+            });
+            return { candidate, provider, result: { ...result, expiresAt } };
+        }
+        catch (cause) {
+            if (cause instanceof ProviderUnavailableError) {
+                attempts.push({
+                    durationMs: performance.now() - start,
+                    operation,
+                    outcome: 'unavailable',
+                    provider,
+                });
+                return undefined;
+            }
+            attempts.push({
+                cause,
+                durationMs: performance.now() - start,
+                operation,
+                outcome: 'failed',
+                provider,
+            });
+            throw cause;
+        }
+    }));
+    for (const attempt of attempts) {
+        try {
+            options.onAttempt?.(attempt);
+        }
+        catch {
+            // Observability hooks never alter preparation behavior.
+        }
+    }
+    const prepared = results.flatMap((result) => result.status === 'fulfilled' && result.value ? [result.value] : []);
+    if (prepared.length === 0) {
+        const failures = results.flatMap((result, index) => result.status === 'rejected'
+            ? [
+                {
+                    cause: result.reason,
+                    operation,
+                    provider: candidates[index].provider,
+                },
+            ]
+            : []);
+        if (failures.length === 0)
+            return undefined;
+        throw new ProviderQuoteError(failures, attempts);
+    }
+    // Deterministic selection: highest guaranteed minimum, then provider id.
+    prepared.sort((a, b) => {
+        const delta = BigInt(b.result.destinationAmountMin) - BigInt(a.result.destinationAmountMin);
+        if (delta !== 0n)
+            return delta > 0n ? 1 : -1;
+        return a.provider.id < b.provider.id ? -1 : 1;
+    });
+    return prepared[0];
+}
+/**
+ * Returns capability-enabled reusable-address candidates for a route. Tokens
+ * resolve within their chains and only provider delivery qualifies.
+ */
+export function getDepositAddressCandidates(options) {
+    const sourceChain = resolveSourceChain(options.sourceChain, options.catalog);
+    const destinationChainId = `eip155:${options.destinationChainId}`;
+    return options.catalog.routes.flatMap((entry) => {
+        if (entry.route.source.chain.id !== sourceChain.id)
+            return [];
+        if (entry.route.destination.chain.id !== destinationChainId)
+            return [];
+        if (!matchesToken(entry.route.source, options.sourceToken))
+            return [];
+        if (!matchesToken(entry.route.destination, options.destinationToken))
+            return [];
+        if (!entry.capabilities?.depositAddress)
+            return [];
+        const provider = options.providers.find((candidate) => candidate.id === entry.providerId);
+        if (!provider || !canCreateDepositAddress(provider))
+            return [];
+        return [
+            { candidate: createDepositAddressCandidate({ provider, route: entry.route }), provider },
+        ];
+    });
+}
+/**
+ * Returns capability-enabled preparation candidates for a creation request.
+ * Tokens resolve within their chains. A route must enable the requested mode,
+ * and its provider must implement `prepareTransfer`.
+ */
+export function 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}`;
+    return options.catalog.routes.flatMap((entry) => {
+        if (entry.route.source.chain.id !== sourceChain.id)
+            return [];
+        if (entry.route.destination.chain.id !== destinationChainId)
+            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 [];
+        const provider = options.providers.find((candidate) => candidate.id === entry.providerId);
+        if (!provider || !canPrepareTransfer(provider))
+            return [];
+        return [
+            {
+                candidate: createQuoteCandidate({
+                    destinationToken: entry.route.destination,
+                    provider,
+                    route: entry.route,
+                    sourceAmount: resolveSourceAmount({
+                        amount: options.sourceAmount,
+                        token: entry.route.source,
+                        units: 'baseUnits',
+                    }),
+                    sourceToken: entry.route.source,
+                }),
+                provider,
+            },
+        ];
+    });
+}
+/** Returns bounded provider failure details suitable for structured request logs. */
+export function failure(options) {
+    const { cause, operation, provider } = options;
+    if (cause instanceof ProviderTimeoutError ||
+        (cause instanceof DOMException && cause.name === 'AbortError'))
+        return { failure: 'timeout', id: provider.id, operation };
+    if (cause instanceof ProviderResponseError) {
+        const code = errorCode(cause.body);
+        return {
+            ...(code === undefined ? {} : { code }),
+            failure: 'http',
+            id: provider.id,
+            operation,
+            status: cause.status,
+        };
+    }
+    if (cause instanceof ProviderPayloadError)
+        return { failure: 'payload', id: provider.id, operation };
+    if (cause instanceof ProviderRateLimitError)
+        return { failure: 'rate_limit', id: provider.id, operation };
+    if (cause instanceof TypeError)
+        return { failure: 'network', id: provider.id, operation };
+    return { failure: 'unknown', id: provider.id, operation };
+}
+/** Returns a supported expected-unavailable code from a provider response. */
+export function unavailable(cause, codes) {
+    if (!(cause instanceof ProviderResponseError) || cause.status < 400 || cause.status >= 500)
+        return undefined;
+    const code = errorCode(cause.body);
+    if (code && codes.includes(code))
+        return code;
+    return undefined;
+}
+/** Requests and parses a JSON provider response. */
+export async function requestJson(url, options) {
+    const headers = { accept: 'application/json', ...options.headers };
+    const init = {
+        headers: options.body === undefined ? headers : { ...headers, 'content-type': 'application/json' },
+        method: options.method ?? 'GET',
+        signal: options.signal,
+    };
+    if (options.body !== undefined)
+        init.body = JSON.stringify(options.body);
+    const response = await options.fetch(url, init);
+    const text = await response.text();
+    const body = (() => {
+        if (!text)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    })();
+    if (!response.ok)
+        throw new ProviderResponseError(response.status, body);
+    return body;
+}
+/** Creates a normalized expected-unavailable quote result. */
+export function unavailableResult(options) {
+    return {
+        quality: {
+            liquiditySource: options.source,
+            sourceDetail: `${options.detail}:${options.message}`,
+            tier: 'unavailable',
+        },
+        sampledAt: options.now.toISOString(),
+        status: 'unavailable',
+    };
+}
+function tokenKey(token) {
+    const namespace = (() => {
+        if (token.chain.kind === 'solana')
+            return 'token';
+        if (token.chain.kind === 'tron')
+            return 'trc20';
+        return 'erc20';
+    })();
+    return `${token.chain.id}/${namespace}:${token.address}`;
+}
+async function quoteCandidate(candidate, options) {
+    const result = schema.GetQuoteResult.safeParse(await withTimeout((signal) => options.provider.getQuote({
+        candidate,
+        cache: options.cache,
+        destinationChain: candidate.destinationChain,
+        destinationToken: candidate.destinationToken,
+        request: options.request,
+        route: candidate.route,
+        sourceAmount: candidate.sourceAmount,
+        sourceChain: candidate.sourceChain,
+        sourceToken: candidate.sourceToken,
+    }, signal), options.timeoutMs));
+    if (!result.success)
+        throw new ProviderPayloadError();
+    const quote = result.data;
+    if (quote.status === 'unavailable')
+        return { outcome: quote.status };
+    if ((quote.status !== 'available' && quote.status !== 'thin') ||
+        quote.destinationAmount === undefined ||
+        quote.destinationAmount === null)
+        throw new ProviderPayloadError();
+    const destinationAmount = BigInt(quote.destinationAmount);
+    const destinationAmountMin = quote.destinationAmountMin === undefined ? undefined : BigInt(quote.destinationAmountMin);
+    if (destinationAmount === 0n ||
+        destinationAmountMin === 0n ||
+        (destinationAmountMin !== undefined && destinationAmountMin > destinationAmount))
+        throw new ProviderPayloadError();
+    return {
+        outcome: quote.status,
+        quote: createQuote(candidate, {
+            ...quote,
+            destinationAmount: quote.destinationAmount,
+            status: quote.status,
+        }),
+    };
+}
+function tokenRef(token) {
+    return schema.TokenRef.parse({
+        address: token.address,
+        currency: token.currency,
+        decimals: token.decimals,
+        name: token.name,
+        standard: token.standard,
+        symbol: token.symbol,
+        tokenKey: tokenKey(token),
+        verified: true,
+    });
+}
+function chainRef(chain) {
+    return schema.ChainRef.parse({
+        addressFormat: chain.addressFormat,
+        id: chain.id,
+        kind: chain.kind,
+        name: chain.name,
+    });
+}
+function createDepositAddressCandidate(options) {
+    return {
+        destinationChain: chainRef(options.route.destination.chain),
+        destinationToken: tokenRef(options.route.destination),
+        provider: schema.ProviderRef.parse(options.provider),
+        route: options.route,
+        sourceChain: chainRef(options.route.source.chain),
+        sourceToken: tokenRef(options.route.source),
+    };
+}
+function createQuoteCandidate(options) {
+    return {
+        destinationChain: chainRef(options.destinationToken.chain),
+        destinationToken: tokenRef(options.destinationToken),
+        id: [
+            options.sourceToken.chain.slug,
+            options.sourceToken.slug,
+            options.destinationToken.chain.slug,
+            options.destinationToken.slug,
+            options.provider.id,
+        ].join('-'),
+        provider: schema.ProviderRef.parse(options.provider),
+        route: options.route,
+        sourceAmount: options.sourceAmount,
+        sourceChain: chainRef(options.sourceToken.chain),
+        sourceToken: tokenRef(options.sourceToken),
+    };
+}
+function normalizeInput(value) {
+    return value.trim().toLowerCase();
+}
+function parseBaseUnits(value) {
+    return BigInt(value).toString();
+}
+function parseDecimalUnits(value, decimals) {
+    const fraction = value.split('.')[1]?.replace(/0+$/, '') ?? '';
+    if (fraction.length > decimals)
+        throw new InvalidAmountError();
+    try {
+        const amount = core_Value.from(value, decimals);
+        if (amount <= 0n)
+            throw new InvalidAmountError();
+        return amount.toString();
+    }
+    catch (cause) {
+        if (cause instanceof InvalidAmountError)
+            throw cause;
+        throw new InvalidAmountError();
+    }
+}
+function createQuote(candidate, quote) {
+    return schema.FundingQuote.parse({
+        destinationAmount: Value.tokenAmount({
+            baseUnits: quote.destinationAmount,
+            currency: candidate.destinationToken.currency,
+            decimals: candidate.destinationToken.decimals,
+        }),
+        ...(quote.destinationAmountMin !== undefined
+            ? {
+                destinationAmountMin: Value.tokenAmount({
+                    baseUnits: quote.destinationAmountMin,
+                    currency: candidate.destinationToken.currency,
+                    decimals: candidate.destinationToken.decimals,
+                }),
+            }
+            : {}),
+        destinationChain: candidate.destinationChain,
+        destinationToken: candidate.destinationToken,
+        id: candidate.id,
+        provider: candidate.provider,
+        quality: {
+            ...(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: {
+            ...(quote.expiresAt !== undefined ? { expiresAt: quote.expiresAt } : {}),
+            sampledAt: quote.sampledAt,
+        },
+        sourceAmount: Value.tokenAmount({
+            baseUnits: candidate.sourceAmount.amount,
+            currency: candidate.sourceToken.currency,
+            decimals: candidate.sourceToken.decimals,
+        }),
+        sourceChain: candidate.sourceChain,
+        sourceToken: candidate.sourceToken,
+    });
+}
+function withTimeout(fn, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    // Some provider implementations may not honor the signal, so the boundary also races them.
+    return Promise.race([
+        fn(controller.signal),
+        new Promise((_, reject) => {
+            if (controller.signal.aborted) {
+                reject(new ProviderTimeoutError());
+                return;
+            }
+            controller.signal.addEventListener('abort', () => reject(new ProviderTimeoutError()), {
+                once: true,
+            });
+        }),
+    ]).finally(() => clearTimeout(timeout));
+}
+function errorCode(input) {
+    const result = schema.ErrorBody.safeParse(input);
+    if (!result.success)
+        return undefined;
+    const body = result.data;
+    const code = body._tag ??
+        body.code ??
+        body.errorCode ??
+        body.errorType ??
+        body.type ??
+        body.error?.code ??
+        body.error?.type;
+    const parsed = schema.ErrorCode.safeParse(code);
+    return parsed.success ? parsed.data : undefined;
+}
+function attemptResult(attempt) {
+    return {
+        durationMs: attempt.durationMs,
+        ...(attempt.outcome === 'failed'
+            ? {
+                failure: failure({
+                    cause: attempt.cause,
+                    operation: attempt.operation,
+                    provider: attempt.provider,
+                }).failure,
+            }
+            : {}),
+        id: attempt.provider.id,
+        operation: attempt.operation,
+        outcome: attempt.outcome,
+    };
+}
+function resolveDestinationToken(input, catalog) {
+    const destinations = uniqueBy(catalog.routes.map((entry) => entry.route.destination), (token) => `${token.chain.id}:${token.address}`);
+    if (input === undefined) {
+        const destination = destinations.find((candidate) => candidate.slug === defaultDestinationToken);
+        if (!destination)
+            throw new UnsupportedDestinationTokenError();
+        return destination;
+    }
+    const destination = destinations.find((candidate) => matchesToken(candidate, input));
+    if (!destination)
+        throw new UnsupportedDestinationTokenError();
+    return destination;
+}
+function resolveProvider(input, providers) {
+    const provider = providers.find((candidate) => candidate.id === normalizeInput(input));
+    if (!provider)
+        throw new UnsupportedProviderError();
+    return provider;
+}
+function resolveSourceAmount(options) {
+    const amount = options.units === 'baseUnits'
+        ? parseBaseUnits(options.amount)
+        : parseDecimalUnits(options.amount, options.token.decimals);
+    return {
+        amount,
+        formatted: core_Value.format(BigInt(amount), options.token.decimals),
+    };
+}
+function resolveSourceToken(chain, input, catalog) {
+    const tokens = catalog.routes
+        .filter((entry) => entry.route.source.chain.id === chain.id)
+        .map((entry) => entry.route.source);
+    return tokens.find((token) => matchesToken(token, input));
+}
+function matchesToken(token, input) {
+    const trimmed = input.trim();
+    const normalized = normalizeInput(input);
+    return (token.slug === normalized ||
+        token.symbol.toLowerCase() === normalized ||
+        matchesTokenIdentifier(token.chain, token.address, trimmed, normalized) ||
+        matchesTokenIdentifier(token.chain, tokenKey(token), trimmed, normalized));
+}
+function matchesTokenIdentifier(chain, candidate, trimmed, normalized) {
+    return chain.kind === 'evm' ? candidate.toLowerCase() === normalized : candidate === trimmed;
+}
+function resolveSourceChain(input, catalog) {
+    const normalized = normalizeInput(input);
+    const chain = catalog.chainsByKey.get(normalized);
+    if (!chain || !catalog.routes.some((entry) => entry.route.source.chain.id === chain.id))
+        throw new UnsupportedSourceChainError();
+    return chain;
+}
+function getRoutes(catalog, providers) {
+    return providers.flatMap((provider) => (catalog.routesByProvider.get(provider.id) ?? []).map((route) => ({ provider, route })));
+}
+function uniqueBy(values, key) {
+    const seen = new Set();
+    return values.filter((value) => {
+        const id = key(value);
+        if (seen.has(id))
+            return false;
+        seen.add(id);
+        return true;
+    });
+}
+function normalizeAccountAddress(value, chain) {
+    if (chain.kind === 'evm')
+        return Address.validate(value, { strict: false }) ? Address.checksum(value) : undefined;
+    try {
+        const bytes = Base58.toBytes(value);
+        if (chain.kind === 'solana')
+            return bytes.length === 32 ? value : undefined;
+        if (bytes.length !== 25 || bytes[0] !== 0x41)
+            return undefined;
+        const payload = bytes.slice(0, 21);
+        const checksum = Hash.sha256(Hash.sha256(payload), { as: 'Bytes' }).slice(0, 4);
+        return Bytes.isEqual(bytes.slice(21), checksum) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Error thrown when the caller supplies an unsupported destination token. */
+export class UnsupportedDestinationTokenError extends Error {
+    name = 'FundingProvider.UnsupportedDestinationTokenError';
+}
+/** Error thrown when a provider webhook cannot be authenticated. */
+export class WebhookAuthenticationError extends Error {
+    name = 'FundingProvider.WebhookAuthenticationError';
+}
+/** Error thrown when an authenticated provider webhook has an invalid body. */
+export class WebhookPayloadError extends Error {
+    name = 'FundingProvider.WebhookPayloadError';
+}
+/** Error thrown when the caller supplies an invalid source amount. */
+export class InvalidAmountError extends Error {
+    name = 'FundingProvider.InvalidAmountError';
+}
+/** Error thrown when the caller supplies an invalid source-chain refund address. */
+export class InvalidRefundAddressError extends Error {
+    name = 'FundingProvider.InvalidRefundAddressError';
+}
+/** Error thrown when provider deployment configuration is invalid. */
+export class ProviderConfigurationError extends Error {
+    name = 'FundingProvider.ProviderConfigurationError';
+}
+/** Error thrown when a provider response does not match the requested quote. */
+export class ProviderPayloadError extends Error {
+    name = 'FundingProvider.ProviderPayloadError';
+}
+/** Error thrown when a provider confirms that no executable route is available. */
+export class ProviderUnavailableError extends Error {
+    name = 'FundingProvider.ProviderUnavailableError';
+}
+/** Error thrown internally when a provider exceeds its quote timeout. */
+export class ProviderTimeoutError extends Error {
+    name = 'FundingProvider.ProviderTimeoutError';
+}
+/** Error thrown when an internal provider quota rejects a quote request. */
+export class ProviderRateLimitError extends Error {
+    name = 'FundingProvider.ProviderRateLimitError';
+}
+/** Error thrown when a provider returns an unsuccessful HTTP response. */
+export class ProviderResponseError extends Error {
+    status;
+    body;
+    name = 'FundingProvider.ProviderResponseError';
+    constructor(
+    /** Provider response status. */
+    status, 
+    /** Parsed provider response body. */
+    body) {
+        super(`Provider request failed with status ${status}`);
+        this.status = status;
+        this.body = body;
+    }
+}
+/** Error thrown when every matching provider fails to produce a quote. */
+export class ProviderQuoteError extends Error {
+    name = 'FundingProvider.ProviderQuoteError';
+    /** Provider failures that prevented a successful quote. */
+    failures;
+    /** Bounded provider attempts retained for request logs. */
+    fundingProviderAttempts;
+    /** First bounded provider failure retained for request logs. */
+    providerFailure;
+    /** Bounded provider failures retained when multiple providers failed. */
+    providerFailures;
+    constructor(failures, attempts = []) {
+        super();
+        this.failures = failures;
+        this.fundingProviderAttempts = attempts.map(attemptResult);
+        const values = failures.map(failure);
+        const first = values[0];
+        if (first)
+            this.providerFailure = first;
+        if (values.length > 1)
+            this.providerFailures = values;
+    }
+}
+/** Error thrown when the caller filters to an unknown provider. */
+export class UnsupportedProviderError extends Error {
+    name = 'FundingProvider.UnsupportedProviderError';
+}
+/** Error thrown when the caller supplies an unsupported source chain. */
+export class UnsupportedSourceChainError extends Error {
+    name = 'FundingProvider.UnsupportedSourceChainError';
+}
+//# sourceMappingURL=Provider.js.map