@gibs/quotes 1.13.0

package/dist/carriers/price-catalogue.d.ts

@@ -0,0 +1,186 @@
+import { type NearIntentsAsset } from '@gibs/bridge-sdk/near-intents';
+import type { CarrierAssetNode } from '../types.js';
+/**
+ * Each built-in carrier's own token price catalogue — LI.FI's `priceUSD` on
+ * `GET /v1/tokens`, Relay's `GET /currencies/token/price`, and NEAR Intents'
+ * `price` on `GET /v0/tokens`.
+ *
+ * WHY THIS EXISTS. The owner's own model for `estimate()`: "get their price
+ * for each token and their fee... then you can use some smart logic to find
+ * the best routes." A provider-model estimate needs a price for BOTH ends of
+ * an edge before it can say anything — see `types.ts`'s `EstimatedHopResult`
+ * doc. `Carrier.estimate` is synchronous (never a network call — see
+ * `types.ts`), so each catalogue here is populated ahead of time (through
+ * `Carrier.prepare`, for LI.FI and Relay) and read back with a plain,
+ * synchronous lookup.
+ *
+ * MISSING PRICE MEANS NO ESTIMATE, NEVER A GUESS. Every catalogue's
+ * `priceUsd` returns `null` for a token it cannot price, and every built-in
+ * carrier's own `estimate()` returns `null` in turn the moment either side
+ * of an edge prices to `null` — see `lifi.ts`, `relay.ts`, `near-intents.ts`.
+ *
+ * SOURCES, READ LIVE — never guessed:
+ * - LI.FI `GET /v1/tokens`: https://docs.li.fi/api-reference/fetch-all-known-tokens
+ *   — each token object carries an optional `priceUSD` string. This module
+ *   reuses `@gibs/bridge-sdk/consolidated-quote`'s own `lifiTokensUrl` and
+ *   `parseLifiTokens` (already written for the token-picker's own price
+ *   column) rather than a second parser for the same response shape.
+ * - Relay `GET /currencies/token/price?address=&chainId=`:
+ *   https://docs.relay.link/references/api/get-token-price — `{ price: number }`,
+ *   ONE token per call. Relay publishes no BULK priced catalogue: its bulk
+ *   listing, `POST /currencies/v2`, carries `chainId`/`address`/`symbol`/`name`/
+ *   `decimals`/`vmType`/`metadata` and NO price field at all (verified against
+ *   `docs.relay.link/references/api/get-currencies-v2` and this repository's
+ *   own recorded capture, `packages/bridge-sdk/src/__fixtures__/relay/currencies-solana.json`,
+ *   2026-09-24). So this module fetches Relay's price per token, once each,
+ *   and caches every one it learns rather than re-asking.
+ * - NEAR Intents `GET /v0/tokens`: every asset already carries its own
+ *   `price` (a number) and `priceUpdatedAt` (an ISO instant) — verified
+ *   against the checked-in capture, `packages/bridge-sdk/src/__fixtures__/near-intents/tokens.json`
+ *   ("price": 3.11 on wrapped NEAR, 2026-09-17). `@gibs/bridge-sdk/near-intents`'s
+ *   `NearIntentsAsset` and `parseNearIntentsTokens` now keep both fields
+ *   (previously dropped — see that module's own change note), so
+ *   {@link nearIntentsPriceCatalogueFromAssets} reads them from the SAME
+ *   asset list `chain-lists.ts`'s `nearIntentsChainListSource` already
+ *   fetches on its own refresh cadence — never a second fetch under a
+ *   second schedule, mirroring how `carriers/near-intents.ts` already reads
+ *   that list for its own request-building.
+ */
+/** One priced token, as a provider's own catalogue reports it. */
+export type CataloguedPrice = {
+    /** The token's own price, in United States dollars per whole (decimal-adjusted) unit. */
+    readonly priceUsd: number;
+    /** When this price was learned, in epoch milliseconds — the catalogue's own clock, not necessarily the provider's. Null when the provider names no timestamp of its own (LI.FI, Relay). */
+    readonly updatedAtMs: number | null;
+};
+/** Looks up one token's own most recent price, synchronously, from whatever a catalogue has already loaded. Never triggers a fetch. */
+export type PriceCatalogue = {
+    /**
+     * @param node - the token to price
+     * @returns its United States dollar price, or null when this catalogue has none
+     */
+    readonly priceUsd: (node: CarrierAssetNode) => number | null;
+};
+/**
+ * The provider-model math every built-in carrier's `estimate()` shares — see
+ * `types.ts`'s `EstimatedHopResult` doc: "a price ratio times (one minus the
+ * carrier's typical fee) minus a fixed cost, calibrated against observed
+ * history." Only the FEE INPUTS differ between LI.FI, Relay and NEAR
+ * Intents; the arithmetic that turns a price pair and a fee model into a
+ * delivered amount is one function, not three copies of it.
+ *
+ * Works in floating-point whole-token units (`Number`, via `formatUnits`),
+ * matching this codebase's existing price-conversion style
+ * (`@gibs/bridge-sdk/prices.ts`'s `computeUsdPriceFromAmountsOut`) — an
+ * ESTIMATE, not a settlement figure, so the precision a `bigint`
+ * fixed-point scheme would add is not worth the extra machinery.
+ *
+ * @param options.amountIn - the input amount, in `from`'s base units
+ * @param options.fromDecimals - `from`'s decimal places
+ * @param options.toDecimals - `to`'s decimal places
+ * @param options.priceFromUsd - `from`'s own United States dollar price, per whole token
+ * @param options.priceToUsd - `to`'s own United States dollar price, per whole token
+ * @param options.percentageFee - every proportional charge this provider is known to apply, summed, as a fraction (0.001 = 0.1%)
+ * @param options.fixedCostUsd - every flat, United States dollar-denominated charge this provider is known to apply, summed
+ * @param options.calibrationFactor - {@link @gibs/quotes/carriers/calibration!CalibrationStore.factor}'s own answer for this provider and chain pair — 1 when uncalibrated
+ * @returns the delivered amount, in `to`'s base units; 0 when the inputs would price below zero
+ */
+export declare const estimateDeliveredAmount: ({ amountIn, fromDecimals, toDecimals, priceFromUsd, priceToUsd, percentageFee, fixedCostUsd, calibrationFactor, }: {
+    readonly amountIn: bigint;
+    readonly fromDecimals: number;
+    readonly toDecimals: number;
+    readonly priceFromUsd: number;
+    readonly priceToUsd: number;
+    readonly percentageFee: number;
+    readonly fixedCostUsd: number;
+    readonly calibrationFactor: number;
+}) => bigint;
+/** What {@link createLifiPriceCatalogue} needs. */
+export type LifiPriceCatalogueOptions = {
+    /** Overrides LI.FI's own API root, mirroring `LifiProviderConfig.baseUrl`. */
+    readonly baseUrl?: string;
+    /** The `fetch` this catalogue's own requests go through. Defaults to the runtime global. */
+    readonly fetchImpl?: typeof fetch;
+    /** The clock a recorded price's `updatedAtMs` reads. Defaults to `Date.now`. */
+    readonly now?: () => number;
+};
+/** A LI.FI {@link PriceCatalogue}, with the async load step `Carrier.prepare` drives. */
+export type LifiPriceCatalogue = PriceCatalogue & {
+    /**
+     * Fetches `GET /v1/tokens` for every chain id among `nodes` not already
+     * loaded, merging results into the cache. A chain already loaded is
+     * skipped — this catalogue fetches each chain's token list AT MOST ONCE
+     * over its own lifetime, per this module's head note.
+     *
+     * THIS METHOD TRUSTS ITS CALLER TO HAVE ALREADY FILTERED `nodes` TO CHAINS
+     * THE PROVIDER ITSELF LISTS. It has no `QuoteClientConfig.neverSendChainIds`
+     * of its own to consult (this package's carriers, not this catalogue,
+     * hold that guard) — `carriers/lifi.ts`'s own `prepare` is where a chain a
+     * host never wants named (PulseChain, for this repository's own host) is
+     * filtered out before this method is ever called.
+     *
+     * @param nodes - every node a search might branch through, already filtered to chains this provider lists — only their `ecosystem === 'evm'` chain ids matter, since LI.FI prices Ethereum-Virtual-Machine chains only
+     */
+    readonly ensureLoaded: (nodes: readonly CarrierAssetNode[]) => Promise<void>;
+};
+/**
+ * Builds LI.FI's own {@link LifiPriceCatalogue}.
+ *
+ * @param options - see {@link LifiPriceCatalogueOptions}
+ * @returns the catalogue
+ */
+export declare const createLifiPriceCatalogue: (options?: LifiPriceCatalogueOptions) => LifiPriceCatalogue;
+/** What {@link createRelayPriceCatalogue} needs. */
+export type RelayPriceCatalogueOptions = {
+    /** Overrides Relay's own API root, mirroring `RelayProviderConfig.baseUrl`. */
+    readonly baseUrl?: string;
+    /** Forwarded as `x-api-key`, when set — see `docs.relay.link/references/api/get-token-price`'s optional auth header. */
+    readonly apiKey?: string;
+    /** The `fetch` this catalogue's own requests go through. Defaults to the runtime global. */
+    readonly fetchImpl?: typeof fetch;
+    /** The clock a recorded price's `updatedAtMs` reads. Defaults to `Date.now`. */
+    readonly now?: () => number;
+};
+/** A Relay {@link PriceCatalogue}, with the async load step `Carrier.prepare` drives. */
+export type RelayPriceCatalogue = PriceCatalogue & {
+    /**
+     * Fetches `GET /currencies/token/price` for every node not already
+     * attempted, in parallel. A token already attempted — priced or not — is
+     * skipped, per this module's head note: Relay has no bulk price endpoint,
+     * so each token is asked for AT MOST ONCE over this catalogue's lifetime.
+     *
+     * THIS METHOD TRUSTS ITS CALLER TO HAVE ALREADY FILTERED `nodes` TO CHAINS
+     * RELAY ITSELF LISTS — see `LifiPriceCatalogue.ensureLoaded`'s identical
+     * note; `carriers/relay.ts`'s own `prepare` is where that filtering happens.
+     *
+     * @param nodes - every node a search might branch through, already filtered to chains this provider lists
+     */
+    readonly ensureLoaded: (nodes: readonly CarrierAssetNode[]) => Promise<void>;
+};
+/**
+ * Builds Relay's own {@link RelayPriceCatalogue}.
+ *
+ * @param options - see {@link RelayPriceCatalogueOptions}
+ * @returns the catalogue
+ */
+export declare const createRelayPriceCatalogue: (options?: RelayPriceCatalogueOptions) => RelayPriceCatalogue;
+/**
+ * Builds a NEAR Intents {@link PriceCatalogue} from an already-loaded asset
+ * list — the SAME list `chain-lists.ts`'s `nearIntentsChainListSource`
+ * fetches and `carriers/near-intents.ts` already reads for its own request
+ * building (`chainList.capability('near-intents')`). No `ensureLoaded` and
+ * no fetch of its own: this catalogue is a pure, synchronous view over data
+ * a caller already has, refreshed on that source's own cadence — see this
+ * module's head note.
+ *
+ * READS THROUGH `findNearIntentsAsset`, NOT A SEPARATE ADDRESS MAP. That
+ * function already resolves a `CarrierAssetNode`'s chain id and address to
+ * the service's own asset record — including the native-asset and
+ * ecosystem-scoping rules `@gibs/bridge-sdk/near-intents`'s own doc lays
+ * out — so this module reuses that lookup rather than rebuilding an
+ * equivalent one that could silently disagree with it.
+ *
+ * @param assets - the parsed `GET /v0/tokens` asset list
+ * @returns the catalogue
+ */
+export declare const nearIntentsPriceCatalogueFromAssets: (assets: readonly NearIntentsAsset[]) => PriceCatalogue;

package/dist/carriers/price-catalogue.js

@@ -0,0 +1,191 @@
+import { formatUnits, parseUnits } from 'viem';
+import { lifiEndpoints, lifiTokensUrl, parseLifiTokens } from '@gibs/bridge-sdk/consolidated-quote';
+import { assetNodeKey } from '@gibs/bridge-sdk/routing';
+import { findNearIntentsAsset } from '@gibs/bridge-sdk/near-intents';
+// ---------------------------------------------------------------------------
+// estimateDeliveredAmount — the arithmetic every built-in carrier shares
+// ---------------------------------------------------------------------------
+/**
+ * The provider-model math every built-in carrier's `estimate()` shares — see
+ * `types.ts`'s `EstimatedHopResult` doc: "a price ratio times (one minus the
+ * carrier's typical fee) minus a fixed cost, calibrated against observed
+ * history." Only the FEE INPUTS differ between LI.FI, Relay and NEAR
+ * Intents; the arithmetic that turns a price pair and a fee model into a
+ * delivered amount is one function, not three copies of it.
+ *
+ * Works in floating-point whole-token units (`Number`, via `formatUnits`),
+ * matching this codebase's existing price-conversion style
+ * (`@gibs/bridge-sdk/prices.ts`'s `computeUsdPriceFromAmountsOut`) — an
+ * ESTIMATE, not a settlement figure, so the precision a `bigint`
+ * fixed-point scheme would add is not worth the extra machinery.
+ *
+ * @param options.amountIn - the input amount, in `from`'s base units
+ * @param options.fromDecimals - `from`'s decimal places
+ * @param options.toDecimals - `to`'s decimal places
+ * @param options.priceFromUsd - `from`'s own United States dollar price, per whole token
+ * @param options.priceToUsd - `to`'s own United States dollar price, per whole token
+ * @param options.percentageFee - every proportional charge this provider is known to apply, summed, as a fraction (0.001 = 0.1%)
+ * @param options.fixedCostUsd - every flat, United States dollar-denominated charge this provider is known to apply, summed
+ * @param options.calibrationFactor - {@link @gibs/quotes/carriers/calibration!CalibrationStore.factor}'s own answer for this provider and chain pair — 1 when uncalibrated
+ * @returns the delivered amount, in `to`'s base units; 0 when the inputs would price below zero
+ */
+export const estimateDeliveredAmount = ({ amountIn, fromDecimals, toDecimals, priceFromUsd, priceToUsd, percentageFee, fixedCostUsd, calibrationFactor, }) => {
+    const amountInWhole = Number(formatUnits(amountIn, fromDecimals));
+    const priceRatio = priceFromUsd / priceToUsd;
+    const grossOutWhole = amountInWhole * priceRatio * (1 - percentageFee);
+    const fixedCostWhole = fixedCostUsd / priceToUsd;
+    const netOutWhole = (grossOutWhole - fixedCostWhole) * calibrationFactor;
+    if (!Number.isFinite(netOutWhole) || netOutWhole <= 0) {
+        return 0n;
+    }
+    return parseUnits(netOutWhole.toFixed(toDecimals), toDecimals);
+};
+/**
+ * Builds LI.FI's own {@link LifiPriceCatalogue}.
+ *
+ * @param options - see {@link LifiPriceCatalogueOptions}
+ * @returns the catalogue
+ */
+export const createLifiPriceCatalogue = (options = {}) => {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const now = options.now ?? Date.now;
+    const prices = new Map();
+    const loadedChainIds = new Set();
+    let inFlight = null;
+    const loadChain = async (chainId) => {
+        const url = options.baseUrl === undefined ? lifiTokensUrl(chainId) : lifiEndpoints(options.baseUrl).tokens(chainId);
+        let response;
+        try {
+            response = await fetchImpl(url);
+        }
+        catch {
+            // Stays unloaded; a later `ensureLoaded` call over the same chain retries.
+            return;
+        }
+        if (!response.ok) {
+            return;
+        }
+        const payload = await response.json().catch(() => null);
+        const tokens = parseLifiTokens(payload, chainId);
+        if (tokens === null) {
+            return;
+        }
+        for (const token of tokens) {
+            if (token.priceUSD === null) {
+                continue;
+            }
+            const price = Number(token.priceUSD);
+            if (!Number.isFinite(price) || price <= 0) {
+                continue;
+            }
+            const key = assetNodeKey({ chainId, address: token.address, ecosystem: 'evm', decimals: token.decimals });
+            prices.set(key, { priceUsd: price, updatedAtMs: now() });
+        }
+        loadedChainIds.add(chainId);
+    };
+    const ensureLoaded = async (nodes) => {
+        const missing = Array.from(new Set(nodes.filter((node) => node.ecosystem === 'evm').map((node) => node.chainId))).filter((chainId) => !loadedChainIds.has(chainId));
+        if (missing.length === 0) {
+            return;
+        }
+        if (inFlight !== null) {
+            await inFlight;
+            return ensureLoaded(nodes);
+        }
+        const task = Promise.all(missing.map(loadChain)).then(() => undefined);
+        inFlight = task;
+        try {
+            await task;
+        }
+        finally {
+            inFlight = null;
+        }
+    };
+    return {
+        priceUsd: (node) => prices.get(assetNodeKey(node))?.priceUsd ?? null,
+        ensureLoaded,
+    };
+};
+/**
+ * Builds Relay's own {@link RelayPriceCatalogue}.
+ *
+ * @param options - see {@link RelayPriceCatalogueOptions}
+ * @returns the catalogue
+ */
+export const createRelayPriceCatalogue = (options = {}) => {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const now = options.now ?? Date.now;
+    const prices = new Map();
+    const attempted = new Set();
+    const loadToken = async (node) => {
+        const key = assetNodeKey(node);
+        if (attempted.has(key)) {
+            return;
+        }
+        attempted.add(key);
+        const base = options.baseUrl === undefined ? 'https://api.relay.link' : options.baseUrl.replace(/\/+$/, '');
+        const url = new URL(`${base}/currencies/token/price`);
+        url.searchParams.set('address', node.address);
+        url.searchParams.set('chainId', node.chainId.toString());
+        let response;
+        try {
+            response = await fetchImpl(url.toString(), {
+                headers: options.apiKey === undefined ? {} : { 'x-api-key': options.apiKey },
+            });
+        }
+        catch {
+            return;
+        }
+        if (!response.ok) {
+            return;
+        }
+        const body = await response.json().catch(() => null);
+        const price = typeof body === 'object' && body !== null ? body.price : undefined;
+        if (typeof price !== 'number' || !Number.isFinite(price) || price <= 0) {
+            return;
+        }
+        prices.set(key, { priceUsd: price, updatedAtMs: now() });
+    };
+    return {
+        priceUsd: (node) => prices.get(assetNodeKey(node))?.priceUsd ?? null,
+        ensureLoaded: async (nodes) => {
+            await Promise.all(nodes.map(loadToken));
+        },
+    };
+};
+// ---------------------------------------------------------------------------
+// NEAR Intents — derived from the already-loaded asset list, no fetch here
+// ---------------------------------------------------------------------------
+/**
+ * Builds a NEAR Intents {@link PriceCatalogue} from an already-loaded asset
+ * list — the SAME list `chain-lists.ts`'s `nearIntentsChainListSource`
+ * fetches and `carriers/near-intents.ts` already reads for its own request
+ * building (`chainList.capability('near-intents')`). No `ensureLoaded` and
+ * no fetch of its own: this catalogue is a pure, synchronous view over data
+ * a caller already has, refreshed on that source's own cadence — see this
+ * module's head note.
+ *
+ * READS THROUGH `findNearIntentsAsset`, NOT A SEPARATE ADDRESS MAP. That
+ * function already resolves a `CarrierAssetNode`'s chain id and address to
+ * the service's own asset record — including the native-asset and
+ * ecosystem-scoping rules `@gibs/bridge-sdk/near-intents`'s own doc lays
+ * out — so this module reuses that lookup rather than rebuilding an
+ * equivalent one that could silently disagree with it.
+ *
+ * @param assets - the parsed `GET /v0/tokens` asset list
+ * @returns the catalogue
+ */
+export const nearIntentsPriceCatalogueFromAssets = (assets) => ({
+    priceUsd: (node) => {
+        const asset = findNearIntentsAsset({
+            assets,
+            chainId: node.chainId,
+            tokenAddress: node.address,
+            ecosystem: node.ecosystem,
+        });
+        if (asset === null || asset.price === null) {
+            return null;
+        }
+        return Number.isFinite(asset.price) && asset.price > 0 ? asset.price : null;
+    },
+});

package/dist/carriers/relay.d.ts

@@ -0,0 +1,97 @@
+import { type Ecosystem } from '@gibs/bridge-sdk/ecosystems';
+import type { ChainListRegistry } from '../chain-lists.js';
+import { type CalibrationStore } from './calibration.js';
+import { type RelayPriceCatalogue } from './price-catalogue.js';
+import type { CarrierHopEdge, ProviderAsker, RelayProviderConfig } from '../types.js';
+/**
+ * Relay as a built-in {@link ProviderAsker}: a plain, forward-solving
+ * `POST /quote/v2` pre-quote, ported from
+ * `packages/ui/src/lib/state/route-search-quotes.ts`'s `askRelayEdge` —
+ * every `gibs.finance` fact replaced by a value read from this carrier's own
+ * {@link CreateRelayCarrierOptions}. See `carriers/lifi.ts`'s head note for
+ * why every request here should go through `UpstreamFunnel.guardedFetch`
+ * bound to `'relay'`.
+ *
+ * `POST /quote/v2` NOW REQUIRES `x-api-key` (verified live 2026-09-23; it did
+ * not before). `relayRequestHeaders` already sends the header only when
+ * `config.apiKey` is set — this carrier forwards whatever the host
+ * configured and never invents a key. WITH NO KEY CONFIGURED, this carrier
+ * still asks (a host may be mid-migration, or deliberately keyless), and the
+ * refusal Relay's own response carries is surfaced through
+ * `readRelayRefusal` exactly as recorded — never replaced with a
+ * locally-invented "missing key" refusal this module has not observed Relay
+ * actually send.
+ */
+/** What {@link createRelayCarrier} needs beyond the edge and amount it is asked about. */
+export type CreateRelayCarrierOptions = {
+    /** Relay's own configuration — the host's api key, referrer, and base url override. */
+    readonly config?: RelayProviderConfig;
+    /** A server-held address, per ecosystem — see `carriers/lifi.ts`'s identical field for the full contract. */
+    readonly probeAddresses?: Readonly<Partial<Record<Ecosystem, string>>>;
+    /** The chain-list registry `chain-lists.ts` builds — read under the `'relay'` key. */
+    readonly chainList: Pick<ChainListRegistry, 'chainIds'>;
+    /** The `fetch` this carrier's own request goes through — see `carriers/lifi.ts`'s identical field. */
+    readonly fetchImpl?: typeof fetch;
+    /**
+     * This carrier's own {@link RelayPriceCatalogue}, backing {@link Carrier.estimate}.
+     * Defaults to `createRelayPriceCatalogue({ baseUrl: config?.baseUrl, apiKey: config?.apiKey, fetchImpl })`.
+     */
+    readonly priceCatalogue?: RelayPriceCatalogue;
+    /**
+     * This carrier's own {@link CalibrationStore}, correcting {@link Carrier.estimate}
+     * against confirmed `ask()` results. Defaults to an in-memory
+     * `createCalibrationStore()` — see `carriers/lifi.ts`'s identical field.
+     */
+    readonly calibrationStore?: CalibrationStore;
+    /**
+     * The host's own application fee on Relay routes, in basis points — Relay's
+     * `appFees` mechanism (`docs.relay.link/features/app-fees`), configured
+     * per host rather than assumed. Undefined or non-positive means no app fee
+     * is modeled — this package invents no gibs figure (compare
+     * `@gibs/bridge-sdk/referral.ts`'s `relayReferralFeeBasisPoints`, which is
+     * gibs's OWN wiring, kept out of this host-agnostic package).
+     */
+    readonly appFeeBasisPoints?: number;
+};
+/**
+ * Which of Relay's published platform-fee tiers an edge most likely falls
+ * under — read from `docs.relay.link/how-it-works/fees` and
+ * `docs.relay.link/references/api/api_core_concepts/fees.md` (both fetched
+ * 2026-09-24): Token Bridge & same-chain Wrap/Unwrap 0.00%, Stablecoin Swap
+ * 0.01%, Major Swap (ETH, BTC, SOL, POL, BNB, PLUME, and any of those paired
+ * with a stablecoin) 0.06%, Minor Swap (everything else) 0.15%.
+ *
+ * WHY THIS IS A HEURISTIC, NOT A LOOKUP. {@link CarrierAssetNode} carries no
+ * token symbol (see `@gibs/bridge-sdk/routing`'s `AssetNode` — only chain
+ * id, address, ecosystem, decimals), and this host-agnostic package keeps no
+ * stablecoin/major-asset registry of its own to classify one. So this
+ * function only ever answers the two tiers it CAN determine from the edge's
+ * own shape, honestly:
+ *
+ * - `'bridge'` — the literal SAME address crosses chains (a real, checkable
+ *   fact: some tokens, most commonly stablecoins deployed through a
+ *   deterministic factory, share one address across chains).
+ * - `'major'` — either side is that chain's OWN native asset. Every chain
+ * this package's built-in carriers reach is presently an Ethereum-Virtual-
+ *   Machine chain whose native coin is ether or a major chain's own gas
+ *   token (BNB, and so on) — Relay's own "major" list — so a native-asset
+ *   edge is major far more often than not.
+ * - `'minor'` — the default for everything else, INCLUDING a stablecoin pair
+ *   this function cannot tell apart from an ordinary token pair without a
+ *   symbol. That misclassification prices 0.15% instead of the true 0.01%,
+ *   a difference `calibrationStore` (keyed per chain pair — see
+ *   `carriers/lifi.ts`'s identical note) absorbs quickly for any pair quoted
+ *   more than a few times, because the SAME pair keeps landing in the same
+ *   true tier.
+ *
+ * @param edge - the candidate hop
+ * @returns the tier
+ */
+export declare const classifyRelaySwapKind: (edge: CarrierHopEdge) => "bridge" | "major" | "minor";
+/**
+ * Builds Relay as a {@link ProviderAsker}.
+ *
+ * @param options - see {@link CreateRelayCarrierOptions}
+ * @returns the carrier
+ */
+export declare const createRelayCarrier: (options: CreateRelayCarrierOptions) => ProviderAsker;