@gibs/quotes 1.13.0

package/dist/carriers/relay.js

@@ -0,0 +1,242 @@
+import { isNativeAsset } from '@gibs/bridge-sdk/ecosystems';
+import { buildRelayPreQuoteRequest, parseRelayPreQuote } from '@gibs/bridge-sdk/pre-quote';
+import { relayQuoteUrl, relayRequestHeaders } from '@gibs/bridge-sdk/relay-quote';
+import { readRelayRefusal } from '../quote-refusals.js';
+import { createCalibrationStore } from './calibration.js';
+import { createRelayPriceCatalogue, estimateDeliveredAmount } from './price-catalogue.js';
+const cannotCarryAnswer = (reason) => ({
+    ok: false,
+    refusal: { kind: 'cannot-carry', reason, minimumAmount: null },
+});
+const couldNotAskAnswer = (reason) => ({
+    ok: false,
+    refusal: { kind: 'could-not-ask', reason, minimumAmount: null },
+});
+/**
+ * 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 const classifyRelaySwapKind = (edge) => {
+    const sameAddress = edge.from.address.toLowerCase() === edge.to.address.toLowerCase();
+    if (sameAddress && edge.from.chainId !== edge.to.chainId) {
+        return 'bridge';
+    }
+    if (isNativeAsset(edge.from.address, edge.from.ecosystem) || isNativeAsset(edge.to.address, edge.to.ecosystem)) {
+        return 'major';
+    }
+    return 'minor';
+};
+/** {@link classifyRelaySwapKind}'s own tier, as a basis-point fraction of the platform fee — see that function's doc for the sources. */
+const relayPlatformFeeFractionByKind = {
+    bridge: 0,
+    major: 0.0006,
+    minor: 0.0015,
+};
+/**
+ * Relay's flat execution charge, in United States dollars — "Relay charges
+ * a $0.02 flat fee... always included," 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.
+ *
+ * DESTINATION GAS IS NOT ADDED TO IT, even though the same source names
+ * "destination (fill) gas estimate" as part of Relay's execution cost
+ * alongside this flat fee. A live destination gas price needs a network
+ * call this package's synchronous `estimate()` cannot make (see `types.ts`'s
+ * `Carrier.estimate` doc), so it is left, along with Relay's own swap-impact
+ * cost, to {@link CalibrationStore} — see `classifyRelaySwapKind`'s doc for
+ * why that correction converges quickly per chain pair.
+ */
+const relayFlatFeeUsd = 0.02;
+/**
+ * Builds Relay as a {@link ProviderAsker}.
+ *
+ * @param options - see {@link CreateRelayCarrierOptions}
+ * @returns the carrier
+ */
+export const createRelayCarrier = (options) => {
+    const { config, probeAddresses, chainList } = options;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const priceCatalogue = options.priceCatalogue ?? createRelayPriceCatalogue({ baseUrl: config?.baseUrl, apiKey: config?.apiKey, fetchImpl });
+    const calibrationStore = options.calibrationStore ?? createCalibrationStore();
+    const appFeeFraction = options.appFeeBasisPoints !== undefined && options.appFeeBasisPoints > 0 ? options.appFeeBasisPoints / 10_000 : 0;
+    /**
+     * A provider-model estimate for this edge — see `types.ts`'s
+     * `Carrier.estimate` doc, `price-catalogue.ts`'s `estimateDeliveredAmount`
+     * for the shared arithmetic, and `classifyRelaySwapKind`/`relayFlatFeeUsd`
+     * for the fee model and its sources.
+     */
+    const estimate = (edge, amountIn) => {
+        const priceFromUsd = priceCatalogue.priceUsd(edge.from);
+        const priceToUsd = priceCatalogue.priceUsd(edge.to);
+        if (priceFromUsd === null || priceToUsd === null)
+            return null;
+        const platformFeeFraction = relayPlatformFeeFractionByKind[classifyRelaySwapKind(edge)];
+        const calibrationFactor = calibrationStore.factor({
+            providerId: 'relay',
+            fromChainId: edge.from.chainId,
+            toChainId: edge.to.chainId,
+        });
+        return {
+            deliveredAmount: estimateDeliveredAmount({
+                amountIn,
+                fromDecimals: edge.from.decimals,
+                toDecimals: edge.to.decimals,
+                priceFromUsd,
+                priceToUsd,
+                percentageFee: platformFeeFraction + appFeeFraction,
+                fixedCostUsd: relayFlatFeeUsd,
+                calibrationFactor,
+            }),
+        };
+    };
+    const edgesFrom = (from, to) => {
+        // Relay's pre-quote body types `destinationCurrency` as `Hex` — the
+        // delivered side of every route this carrier expresses is always an
+        // Ethereum-Virtual-Machine chain, exactly like the plain LI.FI pre-quote.
+        if (to.ecosystem !== 'evm')
+            return [];
+        const chainIds = chainList.chainIds('relay');
+        if (chainIds === null)
+            return [];
+        if (!chainIds.has(from.chainId) || !chainIds.has(to.chainId))
+            return [];
+        return [{ carrier: 'relay', from, to, fusesNext: false, origin: 'wallet', floors: [] }];
+    };
+    const ask = async ({ edge, inputAmount }) => {
+        if (inputAmount <= 0n)
+            return cannotCarryAnswer('non-positive input amount');
+        const fromAddress = probeAddresses?.[edge.from.ecosystem];
+        const recipientAddress = probeAddresses?.evm;
+        if (fromAddress === undefined || recipientAddress === undefined) {
+            return cannotCarryAnswer('no probe address configured for this ecosystem');
+        }
+        const request = {
+            fromChainId: edge.from.chainId,
+            fromTokenAddress: edge.from.address,
+            fromAddress,
+            toChainId: edge.to.chainId,
+            toTokenAddress: edge.to.address,
+            amount: inputAmount,
+            recipient: recipientAddress,
+            ...(edge.from.ecosystem === 'evm' ? {} : { originVmType: edge.from.ecosystem }),
+            // ALWAYS SET, NEVER LEFT `undefined` — `buildRelayPreQuoteRequest` falls
+            // back to `@gibs/bridge-sdk/relay-quote`'s `relayReferrer` constant
+            // ('gibs.finance') when `relayReferrer` is `undefined`. `null` (not
+            // `''`) tells the builder to OMIT the `referrer` field entirely when
+            // the host configured none — Relay's live behavior (verified
+            // 2026-09-23) treats ANY `referrer` value, including `''`, as
+            // "a referrer was supplied" and then requires an api key, so an empty
+            // string would turn an anonymous, keyless ask into a 401. See
+            // `carriers/lifi.ts`'s identical note on `lifiIntegrator`.
+            relayReferrer: config?.referrer ?? null,
+        };
+        const body = buildRelayPreQuoteRequest(request);
+        if (body === null)
+            return cannotCarryAnswer(null);
+        // NEVER ASK A PROVIDER ABOUT A CHAIN IT DOES NOT LIST — see
+        // `carriers/lifi.ts`'s identical guard for why `null` and "loaded but
+        // absent" are answered differently.
+        const chainIds = chainList.chainIds('relay');
+        if (chainIds === null)
+            return couldNotAskAnswer('Relay chain list not loaded');
+        if (!chainIds.has(edge.from.chainId) || !chainIds.has(edge.to.chainId)) {
+            return cannotCarryAnswer("Relay does not list one of this hop's chains");
+        }
+        const quoteUrl = config?.baseUrl === undefined ? relayQuoteUrl : `${config.baseUrl.replace(/\/+$/, '')}/quote/v2`;
+        let response;
+        try {
+            response = await fetchImpl(quoteUrl, {
+                method: 'POST',
+                body: JSON.stringify(body),
+                headers: relayRequestHeaders(config?.apiKey),
+            });
+        }
+        catch (error) {
+            return couldNotAskAnswer(error instanceof Error ? error.message : null);
+        }
+        if (!response.ok) {
+            const responseBody = await response.json().catch(() => null);
+            const refusal = readRelayRefusal(response.status, responseBody);
+            return {
+                ok: false,
+                refusal: {
+                    kind: refusal.kind === 'invalid-api-key' ? 'could-not-ask' : refusal.kind,
+                    reason: refusal.reason,
+                    minimumAmount: refusal.minimumAmount ?? null,
+                },
+            };
+        }
+        const result = parseRelayPreQuote(await response.json());
+        if (result === null)
+            return couldNotAskAnswer('Relay pre-quote response had an unexpected shape');
+        // CALIBRATES `estimate()` AGAINST THIS CONFIRMED QUOTE — see `lifi.ts`'s
+        // identical note.
+        const priorEstimate = estimate(edge, inputAmount);
+        if (priorEstimate !== null) {
+            calibrationStore.record({ providerId: 'relay', fromChainId: edge.from.chainId, toChainId: edge.to.chainId }, result.expectedAmount, priorEstimate.deliveredAmount);
+        }
+        return {
+            ok: true,
+            deliveredAmount: result.expectedAmount,
+            minimumDeliveredAmount: result.minimumAmount,
+            claimedDurationSeconds: null,
+        };
+    };
+    return {
+        id: 'relay',
+        edgesFrom,
+        ask,
+        // Warms `priceCatalogue` for every node the search might branch through,
+        // filtered to chains Relay itself lists FIRST — the same "never name an
+        // unlisted chain to this provider" gate `ask` uses, and the same reason
+        // `lifi.ts`'s identical `prepare` filters too (this codebase's own node
+        // universe includes PulseChain, which Relay's own `/chains` registry
+        // does not list).
+        prepare: async (nodes) => {
+            const chainIds = chainList.chainIds('relay');
+            if (chainIds === null)
+                return;
+            const listedNodes = nodes.filter((node) => chainIds.has(node.chainId));
+            await priceCatalogue.ensureLoaded(listedNodes);
+        },
+        estimate,
+        isRateLimited: true,
+        depositMode: 'wallet-signed',
+        sender: 'aggregator',
+        // A provisional prior for pre-quote scoring, not a measured figure — see
+        // `lifi.ts`'s own note; Relay's own `ask` answers
+        // `claimedDurationSeconds: null` per-quote, above.
+        settlementSeconds: 60,
+    };
+};

package/dist/chain-lists.d.ts

@@ -0,0 +1,144 @@
+import type { CarrierId } from './types.js';
+/** What loading one provider's chain list yields. */
+export type ChainListLoadResult = {
+    /** Every chain id this provider currently lists. */
+    readonly chainIds: readonly number[];
+    /**
+     * Whatever ELSE the same response carried that a carrier's own `ask` might
+     * need — NEAR Intents' full asset list, in particular (see
+     * {@link nearIntentsChainListSource}), so `carriers/near-intents.ts` reads
+     * it from this same cache rather than fetching `/v0/tokens` a second time
+     * under a second refresh cadence. `unknown` here because this module does
+     * not know, and must not know, any built-in carrier's own shape — a
+     * carrier that reads it narrows the type itself.
+     */
+    readonly capability: unknown;
+};
+/** One provider's own chain-list endpoint, read fresh on every {@link ChainListRegistry.refresh} call. */
+export type ChainListSource = {
+    /**
+     * Fetches and parses this provider's own chain list.
+     *
+     * @param fetchImpl - the `fetch` to call through
+     * @throws when the request fails or the response shape is unreadable —
+     *   {@link ChainListRegistry.refresh} catches this and keeps serving the
+     *   last good snapshot rather than propagating it
+     */
+    readonly load: (fetchImpl: typeof fetch) => Promise<ChainListLoadResult>;
+};
+/**
+ * Builds LI.FI's own chain-list source (`GET /v1/chains`).
+ *
+ * @param baseUrl - overrides LI.FI's own API root, mirroring
+ *   `LifiProviderConfig.baseUrl` — omitted uses `lifiChainsUrl` directly
+ * @returns the source
+ */
+export declare const lifiChainListSource: (baseUrl?: string) => ChainListSource;
+/**
+ * Builds Relay's own chain-list source (`GET /chains`).
+ *
+ * @param baseUrl - overrides Relay's own API root, mirroring
+ *   `RelayProviderConfig.baseUrl` — omitted uses `relayChainsUrl` directly
+ * @returns the source
+ */
+export declare const relayChainListSource: (baseUrl?: string) => ChainListSource;
+/**
+ * Builds NEAR Intents' own chain-list source, read off `GET /v0/tokens` —
+ * the service has no chain-listing endpoint of its own, so the chain ids
+ * this exposes are DERIVED, by mapping every asset's `blockchain` short name
+ * through `chainIdByNearIntentsChain` and keeping only the names this
+ * repository already resolves to a chain id (an unresolved name names no
+ * route this codebase can build anyway, so it is dropped rather than
+ * guessed at).
+ *
+ * The full parsed asset list rides along as {@link ChainListLoadResult.capability}
+ * so `carriers/near-intents.ts` can build a request from it directly,
+ * without a second fetch under a second refresh cadence.
+ *
+ * @param baseUrl - overrides NEAR Intents' own API root, mirroring
+ *   `NearIntentsProviderConfig.baseUrl` — omitted uses `nearIntentsTokensUrl` directly
+ * @returns the source
+ */
+export declare const nearIntentsChainListSource: (baseUrl?: string) => ChainListSource;
+/** Every built-in provider's own chain-list source, keyed by {@link CarrierId} — the map {@link createChainListRegistry} is typically built from. */
+export declare const builtInChainListSources: (baseUrls?: Readonly<Partial<Record<"lifi" | "relay" | "near-intents", string>>>) => Readonly<Record<CarrierId, ChainListSource>>;
+/** How often {@link ChainListRegistry.startAutoRefresh} refreshes every registered source. */
+export declare const DEFAULT_CHAIN_LIST_REFRESH_INTERVAL_MS: number;
+/** How long a snapshot is still served after its own refresh cadence would have replaced it, once refreshing itself starts failing. */
+export declare const DEFAULT_CHAIN_LIST_MAX_STALE_MS: number;
+export type CreateChainListRegistryOptions = {
+    /** Every provider (or host carrier) whose chain list this registry loads and refreshes, keyed by {@link CarrierId}. */
+    readonly sources: Readonly<Record<CarrierId, ChainListSource>>;
+    readonly fetch?: typeof fetch;
+    readonly now?: () => number;
+    /** Overrides {@link DEFAULT_CHAIN_LIST_REFRESH_INTERVAL_MS}. */
+    readonly refreshIntervalMs?: number;
+    /** Overrides {@link DEFAULT_CHAIN_LIST_MAX_STALE_MS}. */
+    readonly maxStaleMs?: number;
+};
+/**
+ * Every registered provider's own chain list, on a refresh cadence, with the
+ * could-not-ask-until-loaded gate `docs/quote-service.md` calls for.
+ */
+export type ChainListRegistry = {
+    /** Whether `id` has a usable snapshot right now — loaded, and not yet past its stale grace window. */
+    readonly isLoaded: (id: CarrierId) => boolean;
+    /**
+     * `id`'s own chain ids, or null when there is no usable snapshot —
+     * NEVER LOADED, or loaded but now stale past {@link DEFAULT_CHAIN_LIST_MAX_STALE_MS}.
+     * A carrier reading null must refuse `could-not-ask`, never guess.
+     *
+     * @param id - the carrier or provider id
+     * @returns the chain ids, or null
+     */
+    readonly chainIds: (id: CarrierId) => ReadonlySet<number> | null;
+    /**
+     * `id`'s own {@link ChainListLoadResult.capability} value, or undefined
+     * when there is no usable snapshot. A caller narrows the type itself —
+     * see {@link ChainListLoadResult.capability}'s own doc for why this module
+     * cannot narrow it for them.
+     *
+     * @param id - the carrier or provider id
+     * @returns the capability payload, or undefined
+     */
+    readonly capability: (id: CarrierId) => unknown;
+    /**
+     * `id`'s own snapshot's load time, in epoch milliseconds, or null when
+     * there is no usable snapshot — the figure `docs/quote-service.md`'s
+     * "Cache" section means by "a refresh stamp for the cache's cannot-carry
+     * lifetime": a `cannot-carry` answer cached against this stamp is stale
+     * the moment the stamp moves, because the chain list that justified it
+     * might no longer.
+     *
+     * @param id - the carrier or provider id
+     * @returns the load time, or null
+     */
+    readonly refreshStampMs: (id: CarrierId) => number | null;
+    /**
+     * Refreshes `id`'s own list now, joining an already-in-flight refresh for
+     * the same id rather than starting a second one. A failure is swallowed
+     * here — the previous snapshot (if any) keeps serving until it ages past
+     * the stale window; a host that wants failures logged reads
+     * {@link ChainListRegistry.isLoaded} or {@link ChainListRegistry.refreshStampMs}
+     * itself to notice one never lands.
+     *
+     * @param id - the carrier or provider id
+     * @returns settles once the refresh attempt finishes, success or failure
+     */
+    readonly refresh: (id: CarrierId) => Promise<void>;
+    /** Refreshes every registered id, concurrently. */
+    readonly refreshAll: () => Promise<void>;
+    /** Starts one recurring, unref'd refresh timer per registered id, at {@link CreateChainListRegistryOptions.refreshIntervalMs}. */
+    readonly startAutoRefresh: () => void;
+    /** Cancels every timer {@link ChainListRegistry.startAutoRefresh} started. Idempotent. */
+    readonly stopAutoRefresh: () => void;
+};
+/**
+ * Builds a fresh {@link ChainListRegistry} with no snapshots loaded — every
+ * id refuses `could-not-ask` (via {@link ChainListRegistry.chainIds} returning
+ * null) until its first successful {@link ChainListRegistry.refresh}.
+ *
+ * @param options - see {@link CreateChainListRegistryOptions}
+ * @returns the registry
+ */
+export declare const createChainListRegistry: (options: CreateChainListRegistryOptions) => ChainListRegistry;

package/dist/chain-lists.js

@@ -0,0 +1,169 @@
+import { lifiChainsUrl, lifiEndpoints, lifiRequestHeaders, parseLifiChains } from '@gibs/bridge-sdk/consolidated-quote';
+import { chainIdByNearIntentsChain, nearIntentsRequestHeaders, nearIntentsTokensUrl, parseNearIntentsTokens, } from '@gibs/bridge-sdk/near-intents';
+import { parseRelayChains, relayChainsUrl } from '@gibs/bridge-sdk/relay-currencies';
+const scheduleTimer = (callback, delayMs) => {
+    const handle = setTimeout(callback, Math.max(0, delayMs));
+    if (typeof handle === 'object' && handle !== null && 'unref' in handle) {
+        handle.unref();
+    }
+    return () => clearTimeout(handle);
+};
+/**
+ * Builds LI.FI's own chain-list source (`GET /v1/chains`).
+ *
+ * @param baseUrl - overrides LI.FI's own API root, mirroring
+ *   `LifiProviderConfig.baseUrl` — omitted uses `lifiChainsUrl` directly
+ * @returns the source
+ */
+export const lifiChainListSource = (baseUrl) => ({
+    load: async (fetchImpl) => {
+        const url = baseUrl === undefined ? lifiChainsUrl : lifiEndpoints(baseUrl).chains;
+        const response = await fetchImpl(url, { headers: lifiRequestHeaders() });
+        if (!response.ok) {
+            throw new Error(`LI.FI chains request failed with status ${response.status}`);
+        }
+        const parsed = parseLifiChains(await response.json());
+        if (parsed === null) {
+            throw new Error('LI.FI chains response had an unexpected shape');
+        }
+        return { chainIds: parsed.map((chain) => chain.id), capability: parsed };
+    },
+});
+/**
+ * Builds Relay's own chain-list source (`GET /chains`).
+ *
+ * @param baseUrl - overrides Relay's own API root, mirroring
+ *   `RelayProviderConfig.baseUrl` — omitted uses `relayChainsUrl` directly
+ * @returns the source
+ */
+export const relayChainListSource = (baseUrl) => ({
+    load: async (fetchImpl) => {
+        const url = baseUrl === undefined ? relayChainsUrl : `${baseUrl.replace(/\/+$/, '')}/chains`;
+        const response = await fetchImpl(url);
+        if (!response.ok) {
+            throw new Error(`Relay chains request failed with status ${response.status}`);
+        }
+        const parsed = parseRelayChains(await response.json());
+        if (parsed === null) {
+            throw new Error('Relay chains response had an unexpected shape');
+        }
+        return { chainIds: parsed, capability: parsed };
+    },
+});
+/**
+ * Builds NEAR Intents' own chain-list source, read off `GET /v0/tokens` —
+ * the service has no chain-listing endpoint of its own, so the chain ids
+ * this exposes are DERIVED, by mapping every asset's `blockchain` short name
+ * through `chainIdByNearIntentsChain` and keeping only the names this
+ * repository already resolves to a chain id (an unresolved name names no
+ * route this codebase can build anyway, so it is dropped rather than
+ * guessed at).
+ *
+ * The full parsed asset list rides along as {@link ChainListLoadResult.capability}
+ * so `carriers/near-intents.ts` can build a request from it directly,
+ * without a second fetch under a second refresh cadence.
+ *
+ * @param baseUrl - overrides NEAR Intents' own API root, mirroring
+ *   `NearIntentsProviderConfig.baseUrl` — omitted uses `nearIntentsTokensUrl` directly
+ * @returns the source
+ */
+export const nearIntentsChainListSource = (baseUrl) => ({
+    load: async (fetchImpl) => {
+        const url = baseUrl === undefined ? nearIntentsTokensUrl : `${baseUrl.replace(/\/+$/, '')}/v0/tokens`;
+        const response = await fetchImpl(url, { headers: nearIntentsRequestHeaders() });
+        if (!response.ok) {
+            throw new Error(`NEAR Intents tokens request failed with status ${response.status}`);
+        }
+        const assets = parseNearIntentsTokens(await response.json());
+        const chainIds = new Set();
+        for (const asset of assets) {
+            const chainId = chainIdByNearIntentsChain.get(asset.blockchain);
+            if (chainId !== undefined)
+                chainIds.add(chainId);
+        }
+        return { chainIds: Array.from(chainIds), capability: assets };
+    },
+});
+/** Every built-in provider's own chain-list source, keyed by {@link CarrierId} — the map {@link createChainListRegistry} is typically built from. */
+export const builtInChainListSources = (baseUrls = {}) => ({
+    lifi: lifiChainListSource(baseUrls.lifi),
+    relay: relayChainListSource(baseUrls.relay),
+    'near-intents': nearIntentsChainListSource(baseUrls['near-intents']),
+});
+// ---------------------------------------------------------------------------
+// ChainListRegistry — refresh cadence, staleness, the could-not-ask gate
+// ---------------------------------------------------------------------------
+/** How often {@link ChainListRegistry.startAutoRefresh} refreshes every registered source. */
+export const DEFAULT_CHAIN_LIST_REFRESH_INTERVAL_MS = 10 * 60_000;
+/** How long a snapshot is still served after its own refresh cadence would have replaced it, once refreshing itself starts failing. */
+export const DEFAULT_CHAIN_LIST_MAX_STALE_MS = 60 * 60_000;
+/**
+ * Builds a fresh {@link ChainListRegistry} with no snapshots loaded — every
+ * id refuses `could-not-ask` (via {@link ChainListRegistry.chainIds} returning
+ * null) until its first successful {@link ChainListRegistry.refresh}.
+ *
+ * @param options - see {@link CreateChainListRegistryOptions}
+ * @returns the registry
+ */
+export const createChainListRegistry = (options) => {
+    const fetchImpl = options.fetch ?? fetch;
+    const now = options.now ?? Date.now;
+    const maxStaleMs = options.maxStaleMs ?? DEFAULT_CHAIN_LIST_MAX_STALE_MS;
+    const refreshIntervalMs = options.refreshIntervalMs ?? DEFAULT_CHAIN_LIST_REFRESH_INTERVAL_MS;
+    const snapshots = new Map();
+    const inFlight = new Map();
+    let timers = [];
+    const freshSnapshot = (id) => {
+        const snapshot = snapshots.get(id);
+        if (snapshot === undefined)
+            return null;
+        return now() - snapshot.loadedAtMs > maxStaleMs ? null : snapshot;
+    };
+    const refresh = (id) => {
+        const already = inFlight.get(id);
+        if (already !== undefined)
+            return already;
+        const source = options.sources[id];
+        if (source === undefined)
+            return Promise.resolve();
+        const task = source
+            .load(fetchImpl)
+            .then(({ chainIds, capability }) => {
+            snapshots.set(id, { chainIds: new Set(chainIds), capability, loadedAtMs: now() });
+        })
+            .catch(() => {
+            // See this type's own `refresh` doc: a failed refresh keeps the
+            // previous snapshot (if any) serving rather than clearing it.
+        })
+            .finally(() => {
+            inFlight.delete(id);
+        });
+        inFlight.set(id, task);
+        return task;
+    };
+    return {
+        isLoaded: (id) => freshSnapshot(id) !== null,
+        chainIds: (id) => freshSnapshot(id)?.chainIds ?? null,
+        capability: (id) => freshSnapshot(id)?.capability,
+        refreshStampMs: (id) => freshSnapshot(id)?.loadedAtMs ?? null,
+        refresh,
+        refreshAll: async () => {
+            await Promise.all(Object.keys(options.sources).map((id) => refresh(id)));
+        },
+        startAutoRefresh: () => {
+            for (const id of Object.keys(options.sources)) {
+                const tick = () => {
+                    void refresh(id).finally(() => {
+                        timers.push(scheduleTimer(tick, refreshIntervalMs));
+                    });
+                };
+                timers.push(scheduleTimer(tick, refreshIntervalMs));
+            }
+        },
+        stopAutoRefresh: () => {
+            for (const cancel of timers)
+                cancel();
+            timers = [];
+        },
+    };
+};

package/dist/client.d.ts

@@ -0,0 +1,102 @@
+import { type DisplayQuoteRequest, type DisplayQuoteResponse } from './quote-service-contract.js';
+import { type QuoteUpstreamFunnel } from './upstream.js';
+import type { Carrier, QuoteClientConfig } from './types.js';
+/** The 6 s local-mode per-(ask, carrier) deadline `docs/quote-service.md`'s "Decisions" section names. */
+export declare const DEFAULT_LOCAL_ASK_DEADLINE_MS = 6000;
+/** How long a fallback-to-direct breaker stays open before the next call retries the service — `docs/quote-service.md`'s "Decisions" section: "direct calls for 60 seconds." */
+export declare const SERVICE_BREAKER_MS = 60000;
+/** What a caller supplies beyond {@link QuoteClientConfig} to build a client — the pieces `docs/quote-service.md`'s "Carriers" section leaves to be wired per host. */
+export type QuoteClientOptions = {
+    /**
+     * The carriers this client asks in local mode: built-in aggregators
+     * (LI.FI, Relay, NEAR Intents) or a host's own registered carrier. Their
+     * own network calls are wrapped through an `UpstreamFunnel` this function
+     * builds from {@link QuoteClientConfig.neverSendChainIds} and
+     * {@link QuoteClientConfig.limits} before ever asking one.
+     *
+     * NOT BUILT FROM `QuoteClientConfig.providers` HERE. The real LI.FI/Relay/
+     * NEAR Intents `ProviderAsker` implementations are a later step
+     * (`docs/quote-service.md`'s "Library" section); until they exist, a
+     * caller supplies whatever carriers it already has — real or, in a test,
+     * a fake built against the `Carrier` interface.
+     */
+    readonly carriers?: readonly Carrier[];
+    /** Overrides {@link DEFAULT_LOCAL_ASK_DEADLINE_MS}. */
+    readonly localAskDeadlineMs?: number;
+    /**
+     * Overrides the {@link QuoteUpstreamFunnel} this client would otherwise
+     * build internally from `config.neverSendChainIds`/`config.limits`.
+     *
+     * SUPPLY THIS WHEN `carriers` WERE ALREADY BUILT AGAINST AN EXTERNAL
+     * FUNNEL'S `guardedFetch` — `upstream.ts`'s own head note describes the
+     * pattern: build the funnel first, construct each carrier with
+     * `(input, init) => funnel.guardedFetch(carrierId, input, init)`, THEN
+     * wrap. Passing that SAME funnel instance here keeps its Retry-After
+     * cooldown and concurrency state consistent between the wire-level guard
+     * (`guardedFetch`, already wired into each carrier at construction) and
+     * the structural guard (`wrap`, applied inside this function) — building a
+     * second, independent funnel from the same config would run both guards,
+     * but each against its OWN state, so a `429` the wire-level guard records
+     * would never be seen by the structural one, and `statsSnapshot`'s
+     * `rateLimited429s`/`queueDepth` would read whichever funnel this client
+     * happened to build rather than the one that actually saw the traffic.
+     * Omitted builds a fresh funnel from `config`, exactly as before — correct
+     * whenever `carriers` were NOT built against an external funnel.
+     */
+    readonly funnel?: QuoteUpstreamFunnel;
+    /**
+     * Reads the host's current chain-list refresh generation — forwarded
+     * straight to {@link createAnswerCache}'s own `chainListRefreshStamp`
+     * (`cache.ts`), so a `cannot-carry` entry expires when the host's chain
+     * lists next reload rather than after a fixed duration, per
+     * `docs/quote-service.md`'s "Cache" section: "`cannot-carry` follows the
+     * chain-list refresh." Omitted leaves `cache.ts`'s own default (a
+     * `cannot-carry` entry never expires by generation, only by
+     * least-recently-used eviction) — correct for a caller with no chain-list
+     * registry of its own wired up yet.
+     */
+    readonly chainListRefreshStamp?: () => string;
+};
+/**
+ * The live counters `docs/quote-service.md`'s "Endpoint" section names for
+ * `/stats` — `@gibs/quote-service`'s `QuoteServiceStats` is this same shape,
+ * read straight off {@link QuoteClient.statsSnapshot} rather than recomputed;
+ * see this module's `QuoteClientStatsRecorder` for where each counter is
+ * actually incremented.
+ */
+export type QuoteClientStats = {
+    readonly hits: number;
+    readonly misses: number;
+    readonly joined: number;
+    /** Upstream calls made, keyed by carrier id (`lifi`, `relay`, `near-intents`, or a host-registered carrier). */
+    readonly upstreamCallsByCarrier: Readonly<Record<string, number>>;
+    readonly rateLimited429s: number;
+    readonly queueDepth: number;
+};
+/** What {@link createQuoteClient} returns. */
+export type QuoteClient = {
+    /**
+     * Answers one `POST /v1/display-quotes` request — see
+     * `docs/quote-service.md`'s "Endpoint" section for the full contract.
+     *
+     * @param request - 1 to 24 asks, validated against {@link displayQuoteRequestSchema}
+     * @returns one answer per ask, in ask order
+     */
+    readonly displayQuotes: (request: DisplayQuoteRequest) => Promise<DisplayQuoteResponse>;
+    /**
+     * A live snapshot of this client's own counters — see
+     * {@link QuoteClientStats}. Cheap to call repeatedly (`/stats` polls it);
+     * never resets on read.
+     */
+    readonly statsSnapshot: () => QuoteClientStats;
+};
+/**
+ * Builds a {@link QuoteClient} from {@link QuoteClientConfig} — see this
+ * module's head note and `docs/quote-service.md`'s "Library" section for the
+ * three modes `config` selects between.
+ *
+ * @param config - see {@link QuoteClientConfig}
+ * @param options - see {@link QuoteClientOptions}
+ * @returns the client
+ */
+export declare const createQuoteClient: (config: QuoteClientConfig, options?: QuoteClientOptions) => QuoteClient;