@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/pre-quote.js

@@ -0,0 +1,175 @@
+import { isNonEthereumVirtualMachineOrigin, lifiIntegrator, } from './consolidated-quote.js';
+import { resolveAttribution } from './referral.js';
+import { relayReferrerField, slippageToBasisPoints, } from './relay-quote.js';
+/**
+ * Plain LI.FI swap quote endpoint (forward-solving), re-exported from
+ * `consolidated-quote.js` rather than redeclared here — both modules must
+ * agree on the same address, and a second literal would be free to drift from
+ * it.
+ */
+export { lifiQuoteUrl, lifiRequestHeaders } from './consolidated-quote.js';
+/**
+ * Builds the Relay EXACT_INPUT swap pre-quote body for a fixed input. NO `txs`
+ * are attached: Relay solves FORWARD and reports the delivered anchor amount.
+ *
+ * `recipient` and `refundTo` name TWO DIFFERENT chains and must never be
+ * conflated. `refundTo` is always the user's OWN origin-chain address — Relay
+ * refunds a failed (or, here, never-run) swap on the origin chain, and an
+ * Ethereum fallback address could not receive one there. `recipient` names
+ * where the swap lands on the ENTRY chain (`toChainId`), which is always
+ * Ethereum Virtual Machine — for an Ethereum origin the user's own address
+ * already satisfies that and is the default; for a non-Ethereum origin
+ * (Solana base58, Bitcoin bech32, ...) it does NOT, and Relay's `/quote/v2`
+ * validates the recipient's FORMAT against `toChainId` even though this
+ * pre-quote never executes. Sending the origin account there — as an earlier
+ * version of this builder did, reasoning that an unexecuted quote's recipient
+ * is "informational" — gets Relay's `400 INVALID_ADDRESS` on every
+ * non-Ethereum-origin pre-quote, which starves `fetchBestEntryAnchorPreQuote`
+ * of its only capable provider and surfaces as "No route available" for the
+ * whole non-Ethereum-origin flow. `request.recipient` (an explicit
+ * Ethereum-format address the caller supplies) is therefore REQUIRED for a
+ * non-Ethereum origin; without it this returns null.
+ *
+ * @param request - the provider-agnostic pre-quote request
+ * @returns the request body, or null when the input amount is non-positive or
+ *   a non-Ethereum origin has no explicit Ethereum-format `recipient`
+ */
+export const buildRelayPreQuoteRequest = (request) => {
+    if (request.amount <= 0n) {
+        return null;
+    }
+    const nonEthereumOrigin = isNonEthereumVirtualMachineOrigin(request);
+    // A non-Ethereum origin's own address cannot stand in for an entry-chain
+    // recipient; it must be supplied explicitly. An Ethereum origin's own
+    // address already IS a valid entry-chain address, so it remains the default.
+    const recipient = nonEthereumOrigin ? request.recipient : (request.recipient ?? request.fromAddress);
+    if (recipient === undefined) {
+        return null;
+    }
+    return {
+        user: request.fromAddress,
+        originChainId: request.fromChainId,
+        originCurrency: request.fromTokenAddress,
+        destinationChainId: request.toChainId,
+        destinationCurrency: request.toTokenAddress,
+        amount: request.amount.toString(),
+        tradeType: 'EXACT_INPUT',
+        recipient,
+        // Relay always refunds on the ORIGIN chain, so the origin's own address
+        // is the correct refund target regardless of ecosystem — unlike
+        // `recipient` above, this one is deliberately NOT Ethereum-format for a
+        // non-Ethereum origin.
+        refundTo: request.fromAddress,
+        ...relayReferrerField(request),
+        ...(request.slippage === undefined
+            ? {}
+            : { slippageTolerance: slippageToBasisPoints(request.slippage) }),
+    };
+};
+/**
+ * Builds the plain LI.FI swap pre-quote as a query string for `GET /v1/quote`.
+ * LI.FI's plain `/quote` is forward-solving by construction (`fromAmount` in,
+ * `estimate.toAmount` out), so no trade-type flag is needed.
+ *
+ * Returns null for a non-Ethereum origin (LI.FI cannot bridge across
+ * virtual-machine ecosystems) and for a non-positive input amount.
+ *
+ * @param request - the provider-agnostic pre-quote request
+ * @returns the URL query string (without a leading `?`), or null
+ */
+export const buildLifiPreQuoteRequest = (request) => {
+    if (request.amount <= 0n) {
+        return null;
+    }
+    if (isNonEthereumVirtualMachineOrigin(request)) {
+        return null;
+    }
+    const params = new URLSearchParams({
+        fromChain: request.fromChainId.toString(),
+        toChain: request.toChainId.toString(),
+        fromToken: request.fromTokenAddress,
+        toToken: request.toTokenAddress,
+        fromAmount: request.amount.toString(),
+        fromAddress: request.fromAddress,
+    });
+    // `null` means "no integrator of this caller's own" and OMITS the query
+    // parameter (LI.FI's own schema marks it optional); `undefined` means
+    // "this repository's own default"; a string is sent as-is. See
+    // `PreQuoteRequest.lifiIntegrator`'s doc.
+    const integrator = resolveAttribution(request.lifiIntegrator, lifiIntegrator);
+    if (integrator !== undefined) {
+        params.set('integrator', integrator);
+    }
+    if (request.slippage !== undefined) {
+        params.set('slippage', request.slippage.toString());
+    }
+    return params.toString();
+};
+const asRecord = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return null;
+    }
+    return value;
+};
+/**
+ * Parses a decimal-string amount into a bigint.
+ *
+ * @returns the bigint value, or null when the input is not a parseable amount
+ */
+const parseAmount = (value) => {
+    if (typeof value !== 'string' || value === '') {
+        return null;
+    }
+    try {
+        return BigInt(value);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Assembles the expected/minimum pair, defaulting the minimum to the expected
+ * amount when the provider omits a guaranteed floor. Shared by both parsers so
+ * the fallback rule lives in exactly one place.
+ *
+ * @returns the result, or null when the expected amount is absent
+ */
+const toPreQuoteResult = (expected, minimum) => {
+    const expectedAmount = parseAmount(expected);
+    if (expectedAmount === null) {
+        return null;
+    }
+    const minimumAmount = parseAmount(minimum);
+    return {
+        expectedAmount,
+        minimumAmount: minimumAmount ?? expectedAmount,
+    };
+};
+/**
+ * Parses a Relay EXACT_INPUT pre-quote response. The delivered anchor figures
+ * live under `details.currencyOut`: `amount` (expected) and `minimumAmount`
+ * (guaranteed slippage floor). Verified live against `api.relay.link/quote/v2`.
+ *
+ * @returns the delivered amounts, or null when the payload shape is unexpected
+ */
+export const parseRelayPreQuote = (payload) => {
+    const currencyOut = asRecord(asRecord(asRecord(payload)?.details)?.currencyOut);
+    if (!currencyOut) {
+        return null;
+    }
+    return toPreQuoteResult(currencyOut.amount, currencyOut.minimumAmount);
+};
+/**
+ * Parses a plain LI.FI `/quote` response. The delivered anchor figures live
+ * under `estimate`: `toAmount` (expected) and `toAmountMin` (guaranteed minimum
+ * after slippage) — the same estimate shape the route-step normalizer reads.
+ *
+ * @returns the delivered amounts, or null when the payload shape is unexpected
+ */
+export const parseLifiPreQuote = (payload) => {
+    const estimate = asRecord(asRecord(payload)?.estimate);
+    if (!estimate) {
+        return null;
+    }
+    return toPreQuoteResult(estimate.toAmount, estimate.toAmountMin);
+};

package/dist/prices.d.ts

@@ -0,0 +1,107 @@
+import { type Hex } from 'viem';
+import type { Token } from './types.js';
+/**
+ * PulseChain mainnet numeric chain id (`Chains.PLS` = `0x171`). Tokens on this
+ * chain (and its testnet sibling below) are priced on-chain via PulseX rather
+ * than from an off-chain price feed.
+ */
+export declare const PULSECHAIN_CHAIN_ID: number;
+/**
+ * PulseChain V4 testnet numeric chain id (`Chains.V4PLS` = `0x3af`). Shares the
+ * PulseX on-chain pricing path with mainnet.
+ */
+export declare const PULSECHAIN_TESTNET_CHAIN_ID: number;
+/**
+ * Bridged DAI on PulseChain (18 decimals) — the USD anchor stablecoin for
+ * on-chain PulseX pricing. One token's `getAmountsOut` ending in this address
+ * yields that token's USD price directly (DAI is treated as exactly $1).
+ *
+ * Kept as an exported constant so the anchor can be swapped without touching the
+ * pricing math. Mirrors `DAI_ADDRESS` in `packages/tx-report/src/server/prices.ts`.
+ */
+export declare const PULSECHAIN_USD_ANCHOR_ADDRESS: Hex;
+/** Decimals of the {@link PULSECHAIN_USD_ANCHOR_ADDRESS} stablecoin. */
+export declare const PULSECHAIN_USD_ANCHOR_DECIMALS = 18;
+/** Wrapped PLS on PulseChain — the routing intermediary for PulseX paths. */
+export declare const WPLS_ADDRESS: `0x${string}`;
+/** Lowercases an address for case-insensitive map keys and comparisons. */
+export declare const lowercaseAddress: (address: string) => string;
+/**
+ * Map key for a foreign (LI.FI-priced) token: `${chainId}-${lowercased address}`.
+ * Matches the key the UI builds when assembling the LI.FI price map.
+ */
+export declare const lifiPriceKey: (chainId: number, address: string) => string;
+/** True when a chain id is priced on-chain via PulseX (mainnet or V4 testnet). */
+export declare const isPulsechain: (chainId: number) => boolean;
+/**
+ * The PulseChain-origin address a bridged token backs out to, when the token's
+ * `extensions.bridgeInfo` records a PulseChain counterpart. Bridged tokens are
+ * 1:1 with their origin, so the origin's PulseX price is the token's USD value.
+ *
+ * @param token - the token whose PulseChain-origin link to resolve
+ * @returns the PulseChain origin address, or null when the token has no such link
+ */
+export declare const pulsechainOriginAddress: (token: Token) => Hex | null;
+/**
+ * The set of PulseX swap paths to price one whole unit of `token` into the USD
+ * anchor stablecoin. Edge cases collapse to shorter paths:
+ *
+ * - `token` is the stablecoin itself -> no swap needed (priced as exactly 1).
+ * - `token` is WPLS (or the native zero-address) -> `[WPLS, stable]` only.
+ * - otherwise -> both `[token, WPLS, stable]` and `[token, stable]`.
+ *
+ * Returned addresses are always concrete (the native sentinel is rewritten to
+ * WPLS) so they can be fed straight into `getAmountsOut`.
+ *
+ * @param options.token - the token (only its address is read) to build paths for
+ * @param options.wpls - the wrapped-native intermediary (defaults to {@link WPLS_ADDRESS})
+ * @param options.stable - the USD anchor (defaults to {@link PULSECHAIN_USD_ANCHOR_ADDRESS})
+ * @returns `{ paths }` — the candidate paths; empty when the token is the stablecoin
+ */
+export declare const pulsexPricePaths: ({ token, wpls, stable, }: {
+    token: Pick<Token, "address">;
+    wpls?: Hex;
+    stable?: Hex;
+}) => {
+    paths: Hex[][];
+};
+/**
+ * A single `getAmountsOut` outcome: the decoded `bigint[]` on success, or raw
+ * `Hex` return data when the (allowFailure) call reverted. Mirrors the
+ * `multicallRead` return shape so results can be passed in untransformed.
+ */
+export type AmountsOutResult = bigint[] | Hex;
+/**
+ * Reduces every `getAmountsOut` result (across all paths and all routers for one
+ * token) to a single USD price by taking the MAX final output, then scaling out
+ * of the stablecoin's decimals. Failed/empty results are dropped; when none
+ * succeed the price is null (no liquidity).
+ *
+ * @param options.results - the `getAmountsOut` outcomes for the token's paths/routers
+ * @param options.stableDecimals - decimals of the anchor (defaults to {@link PULSECHAIN_USD_ANCHOR_DECIMALS})
+ * @returns the USD price as a number, or null when no path produced a value
+ */
+export declare const computeUsdPriceFromAmountsOut: ({ results, stableDecimals, }: {
+    results: readonly AmountsOutResult[];
+    stableDecimals?: number;
+}) => number | null;
+/**
+ * Resolves a token's USD price using pre-fetched price maps, following the
+ * co-designed precedence:
+ *
+ * 1. PulseChain (mainnet or V4 testnet): the token's own PulseX price.
+ * 2. Bridged PulseChain-origin token: the origin's PulseX price (1:1 value).
+ * 3. Genuinely foreign token: the LI.FI inline price.
+ *
+ * The stablecoin anchor itself resolves to exactly 1. All address lookups are
+ * case-insensitive (maps are keyed by lowercased address).
+ *
+ * @param token - the token to price
+ * @param options.pulsexPrices - lowercased PulseChain address -> USD price
+ * @param options.lifiPrices - `${chainId}-${lowercased address}` -> USD price
+ * @returns the USD price as a number, or null when no source can price it
+ */
+export declare const resolveTokenPriceUsd: (token: Token, { pulsexPrices, lifiPrices, }: {
+    pulsexPrices: Map<string, number>;
+    lifiPrices: Map<string, number>;
+}) => number | null;

package/dist/prices.js

@@ -0,0 +1,162 @@
+import { formatUnits } from 'viem';
+import { Chains, nativeAssetOut } from './config.js';
+/**
+ * PulseChain mainnet numeric chain id (`Chains.PLS` = `0x171`). Tokens on this
+ * chain (and its testnet sibling below) are priced on-chain via PulseX rather
+ * than from an off-chain price feed.
+ */
+export const PULSECHAIN_CHAIN_ID = Number(Chains.PLS);
+/**
+ * PulseChain V4 testnet numeric chain id (`Chains.V4PLS` = `0x3af`). Shares the
+ * PulseX on-chain pricing path with mainnet.
+ */
+export const PULSECHAIN_TESTNET_CHAIN_ID = Number(Chains.V4PLS);
+/**
+ * Bridged DAI on PulseChain (18 decimals) — the USD anchor stablecoin for
+ * on-chain PulseX pricing. One token's `getAmountsOut` ending in this address
+ * yields that token's USD price directly (DAI is treated as exactly $1).
+ *
+ * Kept as an exported constant so the anchor can be swapped without touching the
+ * pricing math. Mirrors `DAI_ADDRESS` in `packages/tx-report/src/server/prices.ts`.
+ */
+export const PULSECHAIN_USD_ANCHOR_ADDRESS = '0xefd766ccb38eaf1dfd701853bfce31359239f305';
+/** Decimals of the {@link PULSECHAIN_USD_ANCHOR_ADDRESS} stablecoin. */
+export const PULSECHAIN_USD_ANCHOR_DECIMALS = 18;
+/** Wrapped PLS on PulseChain — the routing intermediary for PulseX paths. */
+export const WPLS_ADDRESS = nativeAssetOut[Chains.PLS];
+/** The native (gas) token sentinel address used across the dapp. */
+const NATIVE_TOKEN_ADDRESS = '0x0000000000000000000000000000000000000000';
+/** Lowercases an address for case-insensitive map keys and comparisons. */
+export const lowercaseAddress = (address) => address.toLowerCase();
+/** True when two addresses are equal ignoring case (and 0x-checksum casing). */
+const sameAddress = (left, right) => lowercaseAddress(left) === lowercaseAddress(right);
+/**
+ * Map key for a foreign (LI.FI-priced) token: `${chainId}-${lowercased address}`.
+ * Matches the key the UI builds when assembling the LI.FI price map.
+ */
+export const lifiPriceKey = (chainId, address) => `${chainId}-${lowercaseAddress(address)}`;
+/** True when a chain id is priced on-chain via PulseX (mainnet or V4 testnet). */
+export const isPulsechain = (chainId) => chainId === PULSECHAIN_CHAIN_ID || chainId === PULSECHAIN_TESTNET_CHAIN_ID;
+/**
+ * The PulseChain-origin address a bridged token backs out to, when the token's
+ * `extensions.bridgeInfo` records a PulseChain counterpart. Bridged tokens are
+ * 1:1 with their origin, so the origin's PulseX price is the token's USD value.
+ *
+ * @param token - the token whose PulseChain-origin link to resolve
+ * @returns the PulseChain origin address, or null when the token has no such link
+ */
+export const pulsechainOriginAddress = (token) => {
+    const link = token.extensions?.bridgeInfo?.[PULSECHAIN_CHAIN_ID];
+    if (!link) {
+        return null;
+    }
+    return link.tokenAddress;
+};
+/**
+ * The set of PulseX swap paths to price one whole unit of `token` into the USD
+ * anchor stablecoin. Edge cases collapse to shorter paths:
+ *
+ * - `token` is the stablecoin itself -> no swap needed (priced as exactly 1).
+ * - `token` is WPLS (or the native zero-address) -> `[WPLS, stable]` only.
+ * - otherwise -> both `[token, WPLS, stable]` and `[token, stable]`.
+ *
+ * Returned addresses are always concrete (the native sentinel is rewritten to
+ * WPLS) so they can be fed straight into `getAmountsOut`.
+ *
+ * @param options.token - the token (only its address is read) to build paths for
+ * @param options.wpls - the wrapped-native intermediary (defaults to {@link WPLS_ADDRESS})
+ * @param options.stable - the USD anchor (defaults to {@link PULSECHAIN_USD_ANCHOR_ADDRESS})
+ * @returns `{ paths }` — the candidate paths; empty when the token is the stablecoin
+ */
+export const pulsexPricePaths = ({ token, wpls = WPLS_ADDRESS, stable = PULSECHAIN_USD_ANCHOR_ADDRESS, }) => {
+    const address = sameAddress(token.address, NATIVE_TOKEN_ADDRESS) ? wpls : token.address;
+    if (sameAddress(address, stable)) {
+        return { paths: [] };
+    }
+    if (sameAddress(address, wpls)) {
+        return { paths: [[wpls, stable]] };
+    }
+    return {
+        paths: [
+            [address, wpls, stable],
+            [address, stable],
+        ],
+    };
+};
+/**
+ * The final output amount of one `getAmountsOut` result, or null when the call
+ * failed (Hex) or returned an empty array. The last element of a `bigint[]`
+ * `getAmountsOut` is the output-token amount.
+ */
+const finalOutput = (result) => {
+    if (typeof result === 'string') {
+        return null;
+    }
+    if (result.length === 0) {
+        return null;
+    }
+    return result[result.length - 1];
+};
+/**
+ * Reduces every `getAmountsOut` result (across all paths and all routers for one
+ * token) to a single USD price by taking the MAX final output, then scaling out
+ * of the stablecoin's decimals. Failed/empty results are dropped; when none
+ * succeed the price is null (no liquidity).
+ *
+ * @param options.results - the `getAmountsOut` outcomes for the token's paths/routers
+ * @param options.stableDecimals - decimals of the anchor (defaults to {@link PULSECHAIN_USD_ANCHOR_DECIMALS})
+ * @returns the USD price as a number, or null when no path produced a value
+ */
+export const computeUsdPriceFromAmountsOut = ({ results, stableDecimals = PULSECHAIN_USD_ANCHOR_DECIMALS, }) => {
+    const outputs = results.flatMap((result) => {
+        const output = finalOutput(result);
+        return output === null ? [] : [output];
+    });
+    if (outputs.length === 0) {
+        return null;
+    }
+    const maxOutput = outputs.reduce((max, current) => (current > max ? current : max), 0n);
+    if (maxOutput === 0n) {
+        return null;
+    }
+    return Number(formatUnits(maxOutput, stableDecimals));
+};
+/**
+ * Resolves a token's USD price using pre-fetched price maps, following the
+ * co-designed precedence:
+ *
+ * 1. PulseChain (mainnet or V4 testnet): the token's own PulseX price.
+ * 2. Bridged PulseChain-origin token: the origin's PulseX price (1:1 value).
+ * 3. Genuinely foreign token: the LI.FI inline price.
+ *
+ * The stablecoin anchor itself resolves to exactly 1. All address lookups are
+ * case-insensitive (maps are keyed by lowercased address).
+ *
+ * @param token - the token to price
+ * @param options.pulsexPrices - lowercased PulseChain address -> USD price
+ * @param options.lifiPrices - `${chainId}-${lowercased address}` -> USD price
+ * @returns the USD price as a number, or null when no source can price it
+ */
+export const resolveTokenPriceUsd = (token, { pulsexPrices, lifiPrices, }) => {
+    if (isPulsechain(token.chainId)) {
+        if (sameAddress(token.address, PULSECHAIN_USD_ANCHOR_ADDRESS)) {
+            return 1;
+        }
+        return pulsexPrices.get(lowercaseAddress(token.address)) ?? null;
+    }
+    const origin = pulsechainOriginAddress(token);
+    if (origin) {
+        if (sameAddress(origin, PULSECHAIN_USD_ANCHOR_ADDRESS)) {
+            return 1;
+        }
+        // Prefer the bridged origin's on-chain PulseX price. Fall back to the token's
+        // OWN home-chain LI.FI inline price when PulseX cannot price it — a bridged
+        // major (e.g. wrapped ether / wrapped binance coin) whose PulseChain pool path
+        // returns nothing would otherwise resolve to null despite a well-known market
+        // price on its home chain.
+        return (pulsexPrices.get(lowercaseAddress(origin)) ??
+            lifiPrices.get(lifiPriceKey(token.chainId, token.address)) ??
+            null);
+    }
+    return lifiPrices.get(lifiPriceKey(token.chainId, token.address)) ?? null;
+};

package/dist/providers.d.ts

@@ -0,0 +1,221 @@
+import { type ConsolidatedQuote, type ConsolidatedQuoteRequest } from './consolidated-quote.js';
+import { type Provider } from './config.js';
+import type { Ecosystem } from './ecosystems.js';
+import { type PreQuoteRequest, type PreQuoteResult } from './pre-quote.js';
+import { type NearIntentsAsset } from './near-intents.js';
+import type { QuoteFeeToken } from './quote-fees.js';
+/**
+ * A consolidated-route aggregator. Like {@link Ecosystem}, this is the `id` of a
+ * descriptor in {@link providerRegistry}, so adding a provider is one descriptor
+ * rather than an edit spread across a union, a capability conditional, and two
+ * interface-side arrays.
+ */
+export type ProviderId = 'lifi' | 'relay' | 'near-intents';
+/**
+ * Every source a hop or a lookup table can attribute to a name, a logo or a
+ * display colour: a consolidated-route aggregator ({@link ProviderId}), an
+ * omnibridge crossing ({@link Provider}, from `config.ts` — `'pulsechain'` or
+ * `'tokensex'`), or the on-chain PulseChain DEX swap leg, which belongs to
+ * neither registry and is named here as its own literal.
+ *
+ * THE ONE UNION FOR "NAME A CARRIER." Every table a hop's carrier is looked up
+ * in — a logo url, a glyph, a display name — must be typed
+ * `Record<ProviderKey, X>`, never `Record<string, X>`: a table keyed on
+ * `string` accepts a carrier with no entry silently, which is how NEAR
+ * Intents shipped with no logo and how a lower-cased `'pulsex'` drew the
+ * initials tile "PU" instead of the PulseX mark. Typed on this union, a
+ * carrier added to any of its three sources fails to compile until it also
+ * has a name and a mark.
+ *
+ * `'PulseX'` IS SPELLED WITH THAT EXACT CASING, matching `providerKey:
+ * 'PulseX'` in `routing/producers.ts` and every lookup table keyed on it.
+ * `routing/search/graph.ts`'s `HopEdge.carrier` is a plain `CarrierId`
+ * string, not this union — the route-search engine is a plug-in host that
+ * does not close its carrier vocabulary over gibs's own three; every member
+ * of THIS union is still a valid `CarrierId`, just not the only one.
+ */
+export type ProviderKey = ProviderId | Provider | 'PulseX';
+/**
+ * What a provider may need to form a request or read an answer, beyond the
+ * route request itself.
+ *
+ * EVERY FIELD IS OPTIONAL AND MOST PROVIDERS IGNORE ALL OF THEM. LI.FI and Relay
+ * name assets by chain and address, and hand back a signable transaction, so
+ * their builders and parsers are total over the request alone — and they stay
+ * referenced here unchanged, because a function of one argument satisfies a type
+ * of two. NEAR Intents needs more in both directions: it names assets by its own
+ * identifiers, which can only be looked up in its published list, and it answers
+ * with a deposit ADDRESS rather than a transaction, so the chain and token the
+ * transfer must be composed from exist only on the request.
+ *
+ * Kept as one optional record rather than a per-provider generic parameter
+ * because the registry's whole purpose is that callers iterate descriptors
+ * without knowing which provider they hold.
+ */
+export type ProviderQuoteContext = {
+    /**
+     * The NEAR Intents asset list. Its identifiers cannot be constructed from a
+     * chain and an address — see `findNearIntentsAsset`.
+     */
+    nearIntentsAssets?: readonly NearIntentsAsset[];
+    /** The clock, for a provider whose request states a deadline. */
+    now?: Date;
+    /** Distribution-channel tag, for a provider that accepts one. */
+    referral?: string;
+    /**
+     * The request being answered. Needed only by a parser whose response does not
+     * carry enough to build the origin deposit on its own.
+     */
+    request?: ConsolidatedQuoteRequest;
+    /** The paid token, for normalizing a charge denominated in it. */
+    originToken?: QuoteFeeToken;
+    /** The delivered token, for the same reason. */
+    destinationToken?: QuoteFeeToken;
+};
+/**
+ * A self-describing provider: which source ecosystems it can carry, and the
+ * existing request-builders and response-parsers for each of the two quoting
+ * phases. The builders and parsers are REFERENCED, never re-implemented — they
+ * already exist and are tested. Endpoint URLs are intentionally absent: the
+ * transport wrappers that own the endpoint, abort signal, and headers live in
+ * the interface package.
+ */
+export type ProviderDescriptor = {
+    id: ProviderId;
+    label: string;
+    /** The source ecosystems this provider can originate a route from. */
+    supportedSourceEcosystems: readonly Ecosystem[];
+    /**
+     * Whether this provider's executor performs a call on the destination chain
+     * when the funds arrive.
+     *
+     * THE FIELD THAT DECIDES WHAT SHAPE OF ROUTE A PROVIDER CAN CARRY, and the
+     * owner's standing criterion expressed as data rather than as a rule somebody
+     * has to remember.
+     *
+     * True — hand it the omnibridge entry call and the crossing is one signature.
+     * False — it delivers tokens to an address and stops, so a crossing through it
+     * takes TWO signatures: the provider's leg, then the reader signing the entry
+     * call themselves once the funds land.
+     *
+     * It also gates the entry-anchor pre-quote, and that is the part that bites.
+     * That phase takes the LARGEST delivered amount across providers and feeds it
+     * to the execution quote as a fixed exact-output target. A provider that
+     * cannot execute can still deliver more — so letting one bid there raises a
+     * target only it could reach and that nobody can execute, turning a working
+     * route into no route at all. See `selectPreQuoteProviderIds`.
+     */
+    executesDestinationCalls: boolean;
+    /**
+     * The origin chains this provider can perform a destination call FROM, or
+     * `'any'` when every origin it carries can. Read only when
+     * {@link executesDestinationCalls} is true.
+     *
+     * LI.FI IS ETHEREUM ONLY — the owner's rule: its contract-calls endpoint
+     * is what attaches the omnibridge entry call, and from any other origin a
+     * LI.FI leg is an ordinary delivery to the reader's own wallet, followed by
+     * a crossing the reader signs. The route search reads this list, so it never
+     * proposes a fused LI.FI hop it could not have signed.
+     */
+    destinationCallOriginChainIds: readonly number[] | 'any';
+    /**
+     * Whether the destination call this provider performs may carry native
+     * value — the omnibridge's native entry (`wrapAndRelayTokens`) is a payable
+     * call, where every other entry moves a token.
+     *
+     * Relay's is verified: a dry `quote/v2` for Base USD Coin into Ethereum
+     * ether with a value-bearing `wrapAndRelayTokens` call answered 200 at 0.05
+     * ether and refused with `DESTINATION_TX_FAILED` at 0.01 (under the
+     * mediator's floor) — so Relay simulates the call with its value attached
+     * (measured 2026-09-27). LI.FI's is not verified, and its request builder
+     * refuses such a call; this field and that builder must agree (see
+     * `providers.test.ts`).
+     */
+    destinationCallCarriesNativeValue: boolean;
+    /**
+     * Phase one: the plain forward-solving origin-to-anchor swap pre-quote.
+     *
+     * The `context` argument is ignored by every provider that does not need it,
+     * and a builder written to take only the request still satisfies this type.
+     */
+    preQuote: {
+        method: 'GET' | 'POST';
+        build: (request: PreQuoteRequest, context?: ProviderQuoteContext) => string | object | null;
+        parse: (payload: unknown, context?: ProviderQuoteContext) => PreQuoteResult | null;
+    };
+    /** Phase two: the backward-solving execution quote with destination calls. */
+    executionQuote: {
+        method: 'GET' | 'POST';
+        build: (request: ConsolidatedQuoteRequest, context?: ProviderQuoteContext) => object | null;
+        parse: (payload: unknown, context?: ProviderQuoteContext) => ConsolidatedQuote | null;
+    };
+};
+/**
+ * Every integrated provider. LI.FI is first: the interface preserves this order
+ * in its active lists, and LI.FI-first is the existing tie-break that prefers
+ * the verified provider on an equal-cost quote. NEAR Intents is last, so it
+ * wins a tie against neither — appropriate for the one provider whose route
+ * costs the reader a second signature.
+ */
+export declare const providerRegistry: readonly ProviderDescriptor[];
+/**
+ * Looks up a provider descriptor for ANY carrier id, answering null for an id
+ * the registry does not hold. The route-search engine carries hops for
+ * carriers that are not providers at all (a local wrap, a pool swap, a
+ * host's own plug-in), so a caller holding an open carrier id must ask this,
+ * never cast the id to {@link ProviderId} and call {@link providerById}, which
+ * throws for such an id.
+ *
+ * @param id - any carrier id
+ * @returns the descriptor, or null when no provider is registered under `id`
+ */
+export declare const findProviderById: (id: string) => ProviderDescriptor | null;
+/**
+ * Looks up a provider descriptor. Total over the `ProviderId` union; throws only
+ * if the registry is left incomplete.
+ *
+ * @param id - the provider key
+ * @returns the descriptor whose `id` equals `id`
+ */
+export declare const providerById: (id: ProviderId) => ProviderDescriptor;
+/**
+ * The providers that can originate a route from `ecosystem`, in registry order.
+ * This is the data that used to be the hand-written capability conditional.
+ *
+ * @param ecosystem - the source ecosystem
+ * @returns the descriptors whose `supportedSourceEcosystems` include `ecosystem`
+ */
+export declare const providersForOrigin: (ecosystem: Ecosystem) => readonly ProviderDescriptor[];
+/**
+ * The providers that may bid in the entry-anchor pre-quote for an origin.
+ *
+ * A STRICTER LIST THAN {@link providersForOrigin}, AND THE DIFFERENCE IS NOT
+ * COSMETIC. The pre-quote exists for one purpose: to learn, for the reader's
+ * fixed input, how much anchor an entry really delivers, so that figure can
+ * become the exact-output target of the execution quote. The winner is whoever
+ * delivers MOST.
+ *
+ * A provider that cannot execute the entry call can still win that comparison —
+ * it has one less thing to pay for. Its number then becomes a target handed to
+ * the providers that must actually fill it, and they cannot, so the whole entry
+ * produces no route. The failure is silent and looks like an absent quote.
+ *
+ * So the pre-quote is restricted to providers that execute. This is not a
+ * judgement about quality; it is that a pre-quote and an execution quote have
+ * to be answerable by the same provider for the handoff between them to mean
+ * anything.
+ *
+ * @param ecosystem - the source ecosystem
+ * @returns the descriptors that may pre-quote this origin, in registry order
+ */
+export declare const preQuoteProvidersForOrigin: (ecosystem: Ecosystem) => readonly ProviderDescriptor[];
+/**
+ * Whether a provider can quote a request's origin ecosystem, derived from the
+ * registry. Equivalent to `providersForOrigin(...).some(...)`, kept as a named
+ * predicate for the call sites that ask about one provider at a time.
+ *
+ * @param provider - the aggregator under consideration
+ * @param request - the request whose origin is being checked
+ * @returns true when the provider supports the request's origin ecosystem
+ */
+export declare const providerSupportsOrigin: (provider: ProviderId, request: Pick<ConsolidatedQuoteRequest, "originVmType">) => boolean;