@gibs/quotes 1.13.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Gibs Finance
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @gibs/quotes
+
+An isomorphic core for asking cross-chain bridge aggregators (LI.FI, Relay, NEAR Intents) for display and execution quotes. It runs unchanged in a browser or in Node.
+
+The package holds the wire contract, the refusal reader, the carriers, and the guards a host wraps around every upstream call. For the full integration guide, read `llms.txt` in this package.
+
+## Install
+
+```sh
+npm install @gibs/quotes viem
+```
+
+`viem` is a peer dependency. The supported range is `>=2.37.0 <3`.
+
+## Requirements
+
+- Node 20 or later, or a modern browser.
+- The package is ESM only. Use `import`, not `require`.
+- `@gibs/bridge-sdk` is a dependency, and it reaches TON code. A browser bundle needs a global `Buffer`. Install the `buffer` package and set `globalThis.Buffer` before you import this package. Node has it already.
+
+## Example
+
+```ts
+import { createQuoteClient, type QuoteClientConfig } from '@gibs/quotes'
+
+const config: QuoteClientConfig = {
+  // 'direct' lets the client ask the aggregators itself when no service answers.
+  fallback: 'direct',
+}
+
+const client = createQuoteClient(config)
+
+// A snapshot of the client's own counters.
+console.log(client.statsSnapshot())
+```
+
+To ask for quotes, call `client.displayQuotes(request)`. The request shape is `DisplayQuoteRequest`, and `llms.txt` describes it.
+
+## Subpath exports
+
+The root entry re-exports most modules. Subpaths such as `@gibs/quotes/quote-guards`, `@gibs/quotes/upstream`, `@gibs/quotes/carriers/relay`, and `@gibs/quotes/search` let you load one module alone.
+
+## License
+
+ISC

package/dist/cache.d.ts

@@ -0,0 +1,73 @@
+import { type RefusedDisplayAnswer } from './quote-service-contract.js';
+import type { AnswerCache, AnswerCacheEntry } from './types.js';
+/**
+ * The display-quote endpoint's shared, single-flight, least-recently-used
+ * answer cache — `types.ts`'s {@link AnswerCache}, built exactly to
+ * `docs/quote-service.md`'s "Cache" section: 30 s for `quoted`/`no-quote`
+ * answers, 5 s for `could-not-ask`, and a `cannot-carry` answer that lives
+ * until the host's own chain-list refresh generation changes rather than for
+ * a fixed duration.
+ *
+ * ENTRIES ALREADY STORE THEIR OWN `askedAmount` — NO EXTRA BOOKKEEPING
+ * NEEDED. `AnswerCacheEntry.answer` is a {@link DisplayProviderSlot}, and
+ * every `quoted` slot already carries its own `askedAmount` field (see
+ * `quote-service-contract.ts`'s `quotedDisplayAnswerCommonShape`). A caller
+ * deciding whether a cache hit — recorded for a DIFFERENT literal amount in
+ * the same two-significant-figure bucket ({@link displayQuoteCacheKey}
+ * collapses the bucket into the key itself) — may still answer a fresh ask
+ * reads that field directly off the entry; see `client.ts`'s own cache-hit
+ * adaptation for where that read happens.
+ */
+/** The 30 s lifetime `docs/quote-service.md`'s "Cache" section gives `quoted` and `no-quote` entries. */
+export declare const DEFAULT_ANSWER_TTL_MS = 30000;
+/** The 5 s lifetime `docs/quote-service.md`'s "Cache" section gives `could-not-ask` entries. */
+export declare const DEFAULT_COULD_NOT_ASK_TTL_MS = 5000;
+/** The "about 10,000 entries" least-recently-used capacity `docs/quote-service.md`'s "Cache" section names. */
+export declare const DEFAULT_MAX_CACHE_ENTRIES = 10000;
+/** How a host builds an {@link AnswerCache} from this module. */
+export type AnswerCacheConfig = {
+    /** Overrides {@link DEFAULT_ANSWER_TTL_MS}, applied to `quoted` and `no-quote` entries. */
+    readonly ttlMs?: number;
+    /** Overrides {@link DEFAULT_COULD_NOT_ASK_TTL_MS}, applied to `could-not-ask` and `invalid-api-key` entries. */
+    readonly couldNotAskTtlMs?: number;
+    /** Overrides {@link DEFAULT_MAX_CACHE_ENTRIES}. */
+    readonly maxEntries?: number;
+    /** The clock every expiry check reads. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /**
+     * Reads the host's current chain-list refresh generation — any value that
+     * changes exactly when the host's chain lists are next reloaded. A
+     * `cannot-carry` entry recorded under one generation is treated as expired
+     * the moment this reads a different one, per `docs/quote-service.md`'s
+     * "Cache" section: "`cannot-carry` follows the chain-list refresh."
+     *
+     * Defaults to a constant function, so a caller with no chain-list-refresh
+     * concept wired up yet simply never expires a `cannot-carry` entry by
+     * generation (it still evicts under least-recently-used pressure like any
+     * other entry). `client.ts` wires this to a real chain-list registry's own
+     * refresh stamp once one is registered.
+     */
+    readonly chainListRefreshStamp?: () => string;
+};
+/**
+ * Builds a fresh, empty {@link AnswerCache}.
+ *
+ * @param config - see {@link AnswerCacheConfig}
+ * @returns the cache
+ */
+export declare const createAnswerCache: (config?: AnswerCacheConfig) => AnswerCache;
+/**
+ * Whether a cached `no-quote` refusal naming a minimum may still answer a
+ * DIFFERENT literal amount than the one it was recorded for —
+ * `docs/quote-service.md`'s "Cache" section: "A `no-quote` naming a minimum
+ * is reused for another amount only when that amount is also below the
+ * minimum." A `no-quote` naming no minimum, and every other refusal kind, is
+ * reused unconditionally for any amount in its bucket; this function only
+ * ever returns `false` for the one case the rule singles out.
+ *
+ * @param answer - the cached refusal
+ * @param amount - the amount actually being asked now, in base units
+ * @returns whether the cached refusal still applies to `amount`
+ */
+export declare const isNoQuoteMinimumReusableForAmount: (answer: RefusedDisplayAnswer, amount: bigint) => boolean;
+export type { AnswerCache, AnswerCacheEntry };

package/dist/cache.js

@@ -0,0 +1,137 @@
+import { decodeBaseUnitsAmount } from './quote-service-contract.js';
+/**
+ * The display-quote endpoint's shared, single-flight, least-recently-used
+ * answer cache — `types.ts`'s {@link AnswerCache}, built exactly to
+ * `docs/quote-service.md`'s "Cache" section: 30 s for `quoted`/`no-quote`
+ * answers, 5 s for `could-not-ask`, and a `cannot-carry` answer that lives
+ * until the host's own chain-list refresh generation changes rather than for
+ * a fixed duration.
+ *
+ * ENTRIES ALREADY STORE THEIR OWN `askedAmount` — NO EXTRA BOOKKEEPING
+ * NEEDED. `AnswerCacheEntry.answer` is a {@link DisplayProviderSlot}, and
+ * every `quoted` slot already carries its own `askedAmount` field (see
+ * `quote-service-contract.ts`'s `quotedDisplayAnswerCommonShape`). A caller
+ * deciding whether a cache hit — recorded for a DIFFERENT literal amount in
+ * the same two-significant-figure bucket ({@link displayQuoteCacheKey}
+ * collapses the bucket into the key itself) — may still answer a fresh ask
+ * reads that field directly off the entry; see `client.ts`'s own cache-hit
+ * adaptation for where that read happens.
+ */
+/** The 30 s lifetime `docs/quote-service.md`'s "Cache" section gives `quoted` and `no-quote` entries. */
+export const DEFAULT_ANSWER_TTL_MS = 30_000;
+/** The 5 s lifetime `docs/quote-service.md`'s "Cache" section gives `could-not-ask` entries. */
+export const DEFAULT_COULD_NOT_ASK_TTL_MS = 5_000;
+/** The "about 10,000 entries" least-recently-used capacity `docs/quote-service.md`'s "Cache" section names. */
+export const DEFAULT_MAX_CACHE_ENTRIES = 10_000;
+const isRefused = (answer) => answer.status === 'refused';
+/**
+ * The fixed-duration lifetime for one answer, or null when its lifetime is
+ * NOT a duration at all — a `cannot-carry` refusal, governed instead by the
+ * chain-list refresh stamp (see {@link AnswerCacheConfig.chainListRefreshStamp}).
+ *
+ * A `pending` slot is never meant to reach {@link AnswerCache.set} at all —
+ * it is a live placeholder `client.ts` synthesizes when a deadline elapses,
+ * never a recorded answer — but this reads it with the shortest lifetime as
+ * a defensive fallback rather than assuming that invariant holds forever.
+ */
+const fixedTtlMsForAnswer = (answer, ttls) => {
+    if (answer.status === 'quoted')
+        return ttls.ttlMs;
+    if (!isRefused(answer))
+        return ttls.couldNotAskTtlMs;
+    if (answer.kind === 'cannot-carry')
+        return null;
+    if (answer.kind === 'no-quote')
+        return ttls.ttlMs;
+    return ttls.couldNotAskTtlMs;
+};
+/**
+ * Builds a fresh, empty {@link AnswerCache}.
+ *
+ * @param config - see {@link AnswerCacheConfig}
+ * @returns the cache
+ */
+export const createAnswerCache = (config = {}) => {
+    const ttlMs = config.ttlMs ?? DEFAULT_ANSWER_TTL_MS;
+    const couldNotAskTtlMs = config.couldNotAskTtlMs ?? DEFAULT_COULD_NOT_ASK_TTL_MS;
+    const maxEntries = config.maxEntries ?? DEFAULT_MAX_CACHE_ENTRIES;
+    const now = config.now ?? Date.now;
+    const chainListRefreshStamp = config.chainListRefreshStamp ?? (() => 'static');
+    // A `Map` iterates in insertion order, so "delete then re-set on every
+    // access" keeps the map's own order equal to recency — the oldest key is
+    // always whatever `.keys().next()` yields, with no separate bookkeeping.
+    const store = new Map();
+    const inFlight = new Map();
+    const touch = (key, entry) => {
+        store.delete(key);
+        store.set(key, entry);
+    };
+    const evictLeastRecentlyUsedIfFull = (key) => {
+        if (store.has(key) || store.size < maxEntries)
+            return;
+        const oldestKey = store.keys().next().value;
+        if (oldestKey !== undefined)
+            store.delete(oldestKey);
+    };
+    return {
+        get: (key) => {
+            const entry = store.get(key);
+            if (entry === undefined)
+                return null;
+            if (isRefused(entry.answer) && entry.answer.kind === 'cannot-carry') {
+                if (entry.chainListStampAtRecord !== chainListRefreshStamp()) {
+                    store.delete(key);
+                    return null;
+                }
+                touch(key, entry);
+                return { answer: entry.answer, recordedAtMs: entry.recordedAtMs };
+            }
+            const ttl = fixedTtlMsForAnswer(entry.answer, { ttlMs, couldNotAskTtlMs });
+            if (ttl !== null && now() - entry.recordedAtMs >= ttl) {
+                store.delete(key);
+                return null;
+            }
+            touch(key, entry);
+            return { answer: entry.answer, recordedAtMs: entry.recordedAtMs };
+        },
+        set: (key, answer, recordedAtMs) => {
+            evictLeastRecentlyUsedIfFull(key);
+            touch(key, { answer, recordedAtMs, chainListStampAtRecord: chainListRefreshStamp() });
+        },
+        joinOrRun: async (key, task) => {
+            const existing = inFlight.get(key);
+            if (existing !== undefined) {
+                const { answer } = await existing;
+                return { answer, joined: true };
+            }
+            const promise = task().then((answer) => ({ answer, joined: false }));
+            inFlight.set(key, promise);
+            try {
+                return await promise;
+            }
+            finally {
+                // "Removed on settle": a fresh ask under this key after this point
+                // starts its own call rather than joining a call that already ended.
+                inFlight.delete(key);
+            }
+        },
+    };
+};
+/**
+ * Whether a cached `no-quote` refusal naming a minimum may still answer a
+ * DIFFERENT literal amount than the one it was recorded for —
+ * `docs/quote-service.md`'s "Cache" section: "A `no-quote` naming a minimum
+ * is reused for another amount only when that amount is also below the
+ * minimum." A `no-quote` naming no minimum, and every other refusal kind, is
+ * reused unconditionally for any amount in its bucket; this function only
+ * ever returns `false` for the one case the rule singles out.
+ *
+ * @param answer - the cached refusal
+ * @param amount - the amount actually being asked now, in base units
+ * @returns whether the cached refusal still applies to `amount`
+ */
+export const isNoQuoteMinimumReusableForAmount = (answer, amount) => {
+    if (answer.kind !== 'no-quote' || answer.minimumAmount === undefined)
+        return true;
+    return amount < decodeBaseUnitsAmount(answer.minimumAmount);
+};

package/dist/carriers/calibration.d.ts

@@ -0,0 +1,115 @@
+import type { CarrierId } from '../types.js';
+/**
+ * How well a built-in carrier's own {@link EstimatedHopResult} tracks what it
+ * actually delivers, per directed chain pair — the calibration factor the
+ * owner asked for on top of the price-and-fee model: "it's custom for each
+ * provider... gather the logic around how much a user is about to be
+ * charged and do the equations." Each carrier's `estimate()` (`lifi.ts`,
+ * `relay.ts`, `near-intents.ts`) can only price what is DOCUMENTED and
+ * STANDARD — an integrator fee, a published tier, a flat charge. What is not
+ * standard (LI.FI's own per-bridge tool fee, Relay's swap impact and
+ * unclassified pair tiers, NEAR Intents' live `withdrawFee`) shows up as a
+ * gap between the model and a real quote, and because that gap is mostly a
+ * property of the ROUTE (which underlying bridge or pool a chain pair
+ * resolves through), not the amount, it stays roughly stable across
+ * requests for the SAME (provider, fromChain, toChain) triple. This module
+ * tracks the ratio between a confirmed quote and this package's own prior
+ * estimate for it, and lets `estimate()` correct for the gap.
+ *
+ * A PURE STORE. Nothing here fetches or schedules; the only side effect is
+ * {@link CalibrationPersistence.save}, and a caller supplies that — the
+ * default keeps samples in memory only, for a host that wants nothing else.
+ */
+/** Identifies one calibration series: one provider, one directed chain pair. */
+export type CalibrationKey = {
+    readonly providerId: CarrierId;
+    readonly fromChainId: number;
+    readonly toChainId: number;
+};
+/** One observed ratio between a confirmed live quote and this package's own prior estimate for the same edge and amount. */
+export type CalibrationSample = {
+    /** `quotedAmount ÷ estimatedAmount` — see {@link calibrationRatio}. */
+    readonly ratio: number;
+    readonly recordedAtMs: number;
+};
+/** How many recent samples one series keeps — "the last 50 confirmed quotes," the owner's own figure. */
+export declare const MAX_CALIBRATION_SAMPLES = 50;
+/**
+ * Below this many samples, {@link CalibrationStore.factor} answers 1 (no
+ * correction) rather than a median of too few points to trust — a single
+ * noisy quote should not swing a route's ranking.
+ */
+export declare const MIN_CALIBRATION_SAMPLES = 5;
+/** Renders a {@link CalibrationKey} into the flat string a persistence layer stores it under. */
+export declare const calibrationKeyString: ({ providerId, fromChainId, toChainId }: CalibrationKey) => string;
+/**
+ * Computes one sample's ratio from a confirmed live quote and this
+ * package's own prior estimate for the same edge and input amount — both
+ * already in the SAME delivered token's base units, so decimals cancel and
+ * no conversion is needed here.
+ *
+ * @param options.quotedAmount - what a live, confirmed `ask()` actually delivered, in the destination token's base units
+ * @param options.estimatedAmount - what `estimate()` predicted for the SAME edge and input amount, in the same units
+ * @returns the ratio, or null when `estimatedAmount` is non-positive and the ratio would be meaningless
+ */
+export declare const calibrationRatio: ({ quotedAmount, estimatedAmount, }: {
+    readonly quotedAmount: bigint;
+    readonly estimatedAmount: bigint;
+}) => number | null;
+/**
+ * Where a {@link CalibrationStore} keeps its samples between calls — a plain
+ * key/value read and write, so a host can back it with memory, a file, or a
+ * database, and this module never has to know which.
+ */
+export type CalibrationPersistence = {
+    readonly load: (key: string) => readonly CalibrationSample[];
+    readonly save: (key: string, samples: readonly CalibrationSample[]) => void;
+};
+/**
+ * An in-memory {@link CalibrationPersistence} — the default a
+ * {@link createCalibrationStore} caller gets when it supplies none. Samples
+ * live only as long as this object does; a host that wants them to survive a
+ * process restart supplies its own persistence instead.
+ */
+export declare const createInMemoryCalibrationPersistence: () => CalibrationPersistence;
+/**
+ * The running median of `quoted ÷ estimated`, per (provider, fromChain,
+ * toChain), that a carrier's `estimate()` reads to correct its own
+ * price-and-fee figure — see this module's head note.
+ */
+export type CalibrationStore = {
+    /**
+     * The calibration factor to multiply an `estimate()` figure by for `key` —
+     * the median of its recorded ratios, or 1 (no correction) when fewer than
+     * {@link MIN_CALIBRATION_SAMPLES} have been recorded.
+     *
+     * @param key - the provider and directed chain pair
+     * @returns the factor
+     */
+    readonly factor: (key: CalibrationKey) => number;
+    /**
+     * Records one confirmed quote against `key`'s series, keeping at most the
+     * {@link MAX_CALIBRATION_SAMPLES} most recent samples, and persists the
+     * result through {@link CalibrationPersistence.save}. A ratio that cannot
+     * be computed (see {@link calibrationRatio}) records nothing.
+     *
+     * @param key - the provider and directed chain pair
+     * @param quotedAmount - what a live `ask()` actually delivered
+     * @param estimatedAmount - what `estimate()` predicted for the same edge and input amount
+     */
+    readonly record: (key: CalibrationKey, quotedAmount: bigint, estimatedAmount: bigint) => void;
+};
+/** What {@link createCalibrationStore} needs beyond the key it is asked about. */
+export type CreateCalibrationStoreOptions = {
+    /** Where samples are kept between calls. Defaults to {@link createInMemoryCalibrationPersistence}. */
+    readonly persistence?: CalibrationPersistence;
+    /** The clock a recorded sample's `recordedAtMs` reads. Defaults to `Date.now`; a test supplies its own. */
+    readonly now?: () => number;
+};
+/**
+ * Builds a {@link CalibrationStore}.
+ *
+ * @param options - see {@link CreateCalibrationStoreOptions}
+ * @returns the store
+ */
+export declare const createCalibrationStore: (options?: CreateCalibrationStoreOptions) => CalibrationStore;

package/dist/carriers/calibration.js

@@ -0,0 +1,83 @@
+/** How many recent samples one series keeps — "the last 50 confirmed quotes," the owner's own figure. */
+export const MAX_CALIBRATION_SAMPLES = 50;
+/**
+ * Below this many samples, {@link CalibrationStore.factor} answers 1 (no
+ * correction) rather than a median of too few points to trust — a single
+ * noisy quote should not swing a route's ranking.
+ */
+export const MIN_CALIBRATION_SAMPLES = 5;
+/** Renders a {@link CalibrationKey} into the flat string a persistence layer stores it under. */
+export const calibrationKeyString = ({ providerId, fromChainId, toChainId }) => `${providerId}:${fromChainId}:${toChainId}`;
+/**
+ * Computes one sample's ratio from a confirmed live quote and this
+ * package's own prior estimate for the same edge and input amount — both
+ * already in the SAME delivered token's base units, so decimals cancel and
+ * no conversion is needed here.
+ *
+ * @param options.quotedAmount - what a live, confirmed `ask()` actually delivered, in the destination token's base units
+ * @param options.estimatedAmount - what `estimate()` predicted for the SAME edge and input amount, in the same units
+ * @returns the ratio, or null when `estimatedAmount` is non-positive and the ratio would be meaningless
+ */
+export const calibrationRatio = ({ quotedAmount, estimatedAmount, }) => {
+    if (estimatedAmount <= 0n) {
+        return null;
+    }
+    // Both bigints already share one token's base units, so this division is a
+    // dimensionless ratio, not a currency figure — `Number(bigint)`'s usual
+    // 2^53 precision ceiling only blurs the ratio's own last few digits here,
+    // never the correctness of which sample was recorded.
+    return Number(quotedAmount) / Number(estimatedAmount);
+};
+/**
+ * An in-memory {@link CalibrationPersistence} — the default a
+ * {@link createCalibrationStore} caller gets when it supplies none. Samples
+ * live only as long as this object does; a host that wants them to survive a
+ * process restart supplies its own persistence instead.
+ */
+export const createInMemoryCalibrationPersistence = () => {
+    const samplesByKey = new Map();
+    return {
+        load: (key) => samplesByKey.get(key) ?? [],
+        save: (key, samples) => {
+            samplesByKey.set(key, samples);
+        },
+    };
+};
+/** The median of a non-empty array of numbers. */
+const median = (values) => {
+    const sorted = [...values].sort((left, right) => left - right);
+    const middleIndex = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 1) {
+        return sorted[middleIndex];
+    }
+    return (sorted[middleIndex - 1] + sorted[middleIndex]) / 2;
+};
+/**
+ * Builds a {@link CalibrationStore}.
+ *
+ * @param options - see {@link CreateCalibrationStoreOptions}
+ * @returns the store
+ */
+export const createCalibrationStore = (options = {}) => {
+    const persistence = options.persistence ?? createInMemoryCalibrationPersistence();
+    const now = options.now ?? Date.now;
+    return {
+        factor: (key) => {
+            const samples = persistence.load(calibrationKeyString(key));
+            if (samples.length < MIN_CALIBRATION_SAMPLES) {
+                return 1;
+            }
+            return median(samples.map((sample) => sample.ratio));
+        },
+        record: (key, quotedAmount, estimatedAmount) => {
+            const ratio = calibrationRatio({ quotedAmount, estimatedAmount });
+            if (ratio === null) {
+                return;
+            }
+            const keyString = calibrationKeyString(key);
+            const existing = persistence.load(keyString);
+            const next = [...existing, { ratio, recordedAtMs: now() }].slice(-MAX_CALIBRATION_SAMPLES);
+            persistence.save(keyString, next);
+        },
+    };
+};

package/dist/carriers/lifi.d.ts

@@ -0,0 +1,63 @@
+import type { Ecosystem } from '@gibs/bridge-sdk/ecosystems';
+import type { ChainListRegistry } from '../chain-lists.js';
+import { type CalibrationStore } from './calibration.js';
+import { type LifiPriceCatalogue } from './price-catalogue.js';
+import type { LifiProviderConfig, ProviderAsker } from '../types.js';
+/**
+ * LI.FI as a built-in {@link ProviderAsker}: a plain, forward-solving
+ * `GET /v1/quote` pre-quote, ported from
+ * `packages/ui/src/lib/state/route-search-quotes.ts`'s `askLifiEdge` — with
+ * every `gibs.finance` fact (the integrator string, the browser's
+ * never-send-a-key header rule) replaced by a value this carrier reads from
+ * its own {@link CreateLifiCarrierOptions}, never a constant it supplies
+ * itself.
+ *
+ * NO NETWORK CALL HERE IS UNGUARDED. This module never imports `fetch`
+ * itself as a default beyond the runtime global — a host wires `fetchImpl`
+ * to `UpstreamFunnel`'s `guardedFetch` (`upstream.ts`), bound to `'lifi'`,
+ * so the concurrency cap, the Retry-After cooldown, the invalid-key breaker
+ * and the chain-id tripwire all run before this carrier's request ever
+ * leaves the process. Passing no `fetchImpl` (the global `fetch` directly)
+ * is a valid choice ONLY for a test or a caller that has its own guards.
+ */
+/** What {@link createLifiCarrier} needs beyond the edge and amount it is asked about. */
+export type CreateLifiCarrierOptions = {
+    /** LI.FI's own configuration — the host's api key, integrator string, base url override, and referral fee. Every field optional; an absent one is simply never sent. */
+    readonly config?: LifiProviderConfig;
+    /**
+     * A server-held address, per ecosystem, this carrier names as its own
+     * `fromAddress`/`recipient` on a probe — see `QuoteClientConfig.probeAddresses`.
+     * An ecosystem with no address configured here refuses every ask for that
+     * ecosystem as `cannot-carry`, per `docs/quote-service.md`'s "Endpoint" section.
+     */
+    readonly probeAddresses?: Readonly<Partial<Record<Ecosystem, string>>>;
+    /** The chain-list registry `chain-lists.ts` builds — read under the `'lifi'` key. */
+    readonly chainList: Pick<ChainListRegistry, 'chainIds'>;
+    /**
+     * The `fetch` this carrier's own request goes through. See this module's
+     * head note: a host should bind this to `UpstreamFunnel.guardedFetch('lifi', ...)`
+     * so every guard applies. Defaults to the runtime global `fetch`.
+     */
+    readonly fetchImpl?: typeof fetch;
+    /**
+     * This carrier's own {@link LifiPriceCatalogue}, backing {@link Carrier.estimate}.
+     * Defaults to `createLifiPriceCatalogue({ baseUrl: config?.baseUrl, fetchImpl })`
+     * — a caller supplies its own only to inject a stub in a test, or to share
+     * one catalogue across more than one carrier instance.
+     */
+    readonly priceCatalogue?: LifiPriceCatalogue;
+    /**
+     * This carrier's own {@link CalibrationStore}, correcting {@link Carrier.estimate}
+     * against confirmed `ask()` results. Defaults to an in-memory
+     * `createCalibrationStore()` — a caller supplies its own to persist
+     * calibration across process restarts.
+     */
+    readonly calibrationStore?: CalibrationStore;
+};
+/**
+ * Builds LI.FI as a {@link ProviderAsker}.
+ *
+ * @param options - see {@link CreateLifiCarrierOptions}
+ * @returns the carrier
+ */
+export declare const createLifiCarrier: (options: CreateLifiCarrierOptions) => ProviderAsker;