@gibs/quotes 1.13.0

package/dist/client.js

@@ -0,0 +1,402 @@
+import { ecosystemByChainId } from '@gibs/bridge-sdk/relay-quote';
+import { createAnswerCache, isNoQuoteMinimumReusableForAmount } from './cache.js';
+import { displayQuoteCacheKey, scaleToAskedAmount } from './quote-guards.js';
+import { decodeBaseUnitsAmount, displayQuoteRequestSchema, displayQuoteResponseSchema, encodeBaseUnitsAmount, toEstimatedDelivery, toExactAmount, } from './quote-service-contract.js';
+import { createSingleFlightGroup } from './single-flight.js';
+import { createUpstreamFunnel } from './upstream.js';
+/**
+ * `createQuoteClient` — the one function every host, backend or frontend,
+ * builds its `POST /v1/display-quotes` behaviour from. See
+ * `docs/quote-service.md`'s "Library" section for the three modes
+ * {@link QuoteClientConfig} selects between, and this module's own doc
+ * comments for how each is implemented.
+ */
+/** Every provider id the display-quote wire contract can answer for. */
+const ALL_PROVIDER_IDS = ['lifi', 'relay', 'near-intents'];
+/** The 6 s local-mode per-(ask, carrier) deadline `docs/quote-service.md`'s "Decisions" section names. */
+export const DEFAULT_LOCAL_ASK_DEADLINE_MS = 6_000;
+/** 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 const SERVICE_BREAKER_MS = 60_000;
+/**
+ * A fixed cache-key generation for probe addresses, until a later step wires
+ * a real, rotating probe-address generation into this client — see
+ * `types.ts`'s `QuoteClientConfig.probeAddresses` and
+ * `quote-guards.ts`'s `displayQuoteCacheKey`, whose `probeSetVersion`
+ * parameter exists for exactly that rotation.
+ */
+const PROBE_SET_VERSION = 'v1';
+// ---------------------------------------------------------------------------
+// DisplayAsk -> CarrierHopEdge — the known gap this step leaves open
+// ---------------------------------------------------------------------------
+/**
+ * Builds the {@link CarrierHopEdge} one (ask, carrier) pair is asked about.
+ *
+ * `decimals: 0` IS A PLACEHOLDER, NOT A REAL VALUE. `DisplayAsk` carries only
+ * a chain id and a token address on each side — no decimals, because this
+ * wire contract has no token list to read them from yet (`docs/quote-service.md`'s
+ * "Library" section lists "the chain-list loader" as a later step). Every
+ * figure this client computes stays in base units end to end and never
+ * multiplies or divides by a power of ten, so an inaccurate `decimals` here
+ * cannot corrupt an answer — but a `Carrier` implementation that DOES read it
+ * (to format a human-readable amount for logging, say) would see a wrong
+ * value. Flagged here rather than silently guessed at.
+ *
+ * @param ask - the ask being resolved
+ * @param providerId - which carrier this edge is for
+ * @returns the edge
+ */
+const buildHopEdge = (ask, providerId) => {
+    const from = {
+        chainId: ask.from.chainId,
+        address: ask.from.token,
+        ecosystem: ecosystemByChainId(ask.from.chainId),
+        decimals: 0,
+    };
+    const to = {
+        chainId: ask.to.chainId,
+        address: ask.to.token,
+        // `docs/quote-service.md`'s "Endpoint" section: "recipientEcosystem ...
+        // default `ecosystemByChainId(to.chainId)`."
+        ecosystem: ask.recipientEcosystem ?? ecosystemByChainId(ask.to.chainId),
+        decimals: 0,
+    };
+    return { carrier: providerId, from, to, fusesNext: false, origin: 'wallet', floors: [] };
+};
+/** Turns one {@link CarrierAskAnswer} into the wire's {@link DisplayProviderSlot}. */
+const displaySlotFromCarrierAnswer = (carrierAnswer, ask, quotedAtIso) => {
+    if (!carrierAnswer.ok) {
+        const { refusal } = carrierAnswer;
+        // `CarrierRefusalKind` is broader than the wire's own refusal vocabulary
+        // — a local-read bound (`below-minimum`, `above-available`) reads as
+        // `no-quote` on the wire: the carrier considered this amount and, for
+        // its own reasons, declined it, which is exactly what `no-quote` means
+        // to a reader of the response.
+        const kind = refusal.kind === 'below-minimum' || refusal.kind === 'above-available' ? 'no-quote' : refusal.kind;
+        return {
+            status: 'refused',
+            kind,
+            reason: refusal.reason,
+            ...(refusal.minimumAmount === null ? {} : { minimumAmount: encodeBaseUnitsAmount(refusal.minimumAmount) }),
+        };
+    }
+    return {
+        status: 'quoted',
+        basis: 'exact',
+        askedAmount: ask.amount,
+        expectedAmount: toExactAmount(carrierAnswer.deliveredAmount),
+        ...(carrierAnswer.minimumDeliveredAmount === null
+            ? {}
+            : { minimumAmount: toExactAmount(carrierAnswer.minimumDeliveredAmount) }),
+        quotedAt: quotedAtIso,
+        ageMs: 0,
+        cache: 'miss',
+    };
+};
+// ---------------------------------------------------------------------------
+// Cache-hit adaptation — reuse, scale, or fall through to a fresh ask
+// ---------------------------------------------------------------------------
+/**
+ * Whether a cache hit may answer THIS ask, per `docs/quote-service.md`'s
+ * "Cache" and "Rules that never bend" sections: a `pending` placeholder is
+ * never reusable; an `exact` ask only reuses an entry recorded for the
+ * IDENTICAL literal amount (never a scaled figure); a `no-quote` naming a
+ * minimum only reuses for an amount also below that minimum
+ * ({@link isNoQuoteMinimumReusableForAmount}); everything else reuses freely.
+ *
+ * @param answer - the cached entry's own answer
+ * @param ask - the ask being resolved
+ * @param askedAmount - `ask.amount`, decoded
+ * @returns whether the entry may answer this ask
+ */
+const isCacheEntryReusable = (answer, ask, askedAmount) => {
+    if (answer.status === 'pending')
+        return false;
+    if (answer.status === 'quoted') {
+        if ((ask.precision ?? 'estimate-ok') === 'exact') {
+            return decodeBaseUnitsAmount(answer.askedAmount) === askedAmount;
+        }
+        return true;
+    }
+    return isNoQuoteMinimumReusableForAmount(answer, askedAmount);
+};
+/**
+ * Adapts a reusable cache entry into this ask's own answer: unchanged (but
+ * for `ageMs` and `cache`) when its `askedAmount` already matches, or scaled
+ * via {@link scaleToAskedAmount} into a `basis: 'scaled-from-nearby-amount'`
+ * answer otherwise. Only ever called after {@link isCacheEntryReusable}
+ * confirms scaling (or reuse at all) is allowed for this ask.
+ *
+ * @param entry - the cache entry
+ * @param askedAmount - `ask.amount`, decoded
+ * @param nowMs - the current time, for `ageMs`
+ * @returns this ask's own answer
+ */
+const adaptCacheHit = (entry, askedAmount, nowMs) => {
+    const { answer } = entry;
+    const ageMs = Math.max(0, nowMs - entry.recordedAtMs);
+    if (answer.status !== 'quoted')
+        return answer;
+    const recordedAskedAmount = decodeBaseUnitsAmount(answer.askedAmount);
+    if (recordedAskedAmount === askedAmount) {
+        return { ...answer, ageMs, cache: 'hit' };
+    }
+    const rawExpected = decodeBaseUnitsAmount(answer.expectedAmount);
+    const scaledExpected = scaleToAskedAmount(rawExpected, askedAmount, recordedAskedAmount);
+    const scaledMinimum = answer.minimumAmount === undefined
+        ? undefined
+        : scaleToAskedAmount(decodeBaseUnitsAmount(answer.minimumAmount), askedAmount, recordedAskedAmount);
+    return {
+        status: 'quoted',
+        basis: 'scaled-from-nearby-amount',
+        askedAmount: encodeBaseUnitsAmount(askedAmount),
+        quotedAt: answer.quotedAt,
+        ageMs,
+        cache: 'hit',
+        expectedAmount: toEstimatedDelivery(scaledExpected),
+        ...(scaledMinimum === undefined ? {} : { minimumAmount: toEstimatedDelivery(scaledMinimum) }),
+        scaledFrom: { askedAmount: answer.askedAmount, expectedAmount: answer.expectedAmount },
+    };
+};
+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);
+};
+/**
+ * Resolves one provider's slot for one ask: a fresh cache hit answers
+ * immediately; otherwise a fresh or shared upstream ask races the local
+ * deadline — a carrier that misses it yields `pending`, while its call keeps
+ * running in the background and fills the cache for the next reader.
+ *
+ * @param context - see {@link ResolveProviderSlotContext}
+ * @returns this provider's own slot for this ask
+ */
+const resolveProviderSlot = async (context) => {
+    const { ask, providerId, carrier, cache, singleFlight, now, localAskDeadlineMs, stats } = context;
+    const askedAmount = decodeBaseUnitsAmount(ask.amount);
+    const cacheKey = displayQuoteCacheKey(providerId, ask, PROBE_SET_VERSION);
+    const cached = cache.get(cacheKey);
+    if (cached !== null && isCacheEntryReusable(cached.answer, ask, askedAmount)) {
+        stats.recordCacheHit();
+        return adaptCacheHit(cached, askedAmount, now());
+    }
+    const run = async () => {
+        stats.recordUpstreamCall(providerId);
+        const edge = buildHopEdge(ask, providerId);
+        const carrierAnswer = await carrier.ask({ edge, inputAmount: askedAmount });
+        const quotedAtMs = now();
+        const answer = displaySlotFromCarrierAnswer(carrierAnswer, ask, new Date(quotedAtMs).toISOString());
+        cache.set(cacheKey, answer, quotedAtMs);
+        return { answer, askedAmount };
+    };
+    const singleFlightRequest = {
+        bucketKey: cacheKey,
+        askedAmount,
+        precision: ask.precision ?? 'estimate-ok',
+    };
+    let cancelDeadline;
+    const deadline = new Promise((resolve) => {
+        cancelDeadline = scheduleTimer(() => resolve({ kind: 'timeout' }), localAskDeadlineMs);
+    });
+    const settled = singleFlight.ask(singleFlightRequest, run).then((result) => ({ kind: 'settled', result }), (error) => ({ kind: 'error', error }));
+    const winner = await Promise.race([settled, deadline]);
+    cancelDeadline?.();
+    if (winner.kind === 'timeout') {
+        // The shared call is NOT cancelled — it keeps running, and its own
+        // `run` closure fills the cache when it settles, for the next reader
+        // (or the next poll of this same one) to find as a `hit`.
+        return { status: 'pending', retryAfterMs: localAskDeadlineMs };
+    }
+    if (winner.kind === 'error') {
+        const message = winner.error instanceof Error ? winner.error.message : null;
+        return { status: 'refused', kind: 'could-not-ask', reason: message };
+    }
+    if (winner.result.joined) {
+        stats.recordCacheJoined();
+    }
+    else {
+        stats.recordCacheMiss();
+    }
+    return winner.result.answer;
+};
+const runLocally = async (asks, context) => {
+    const answers = [];
+    for (const ask of asks) {
+        const requestedProviderIds = ask.providers ?? ALL_PROVIDER_IDS;
+        const slotEntries = await Promise.all(requestedProviderIds.map(async (providerId) => {
+            const carrier = context.carriers.find((candidate) => candidate.id === providerId);
+            if (carrier === undefined) {
+                // Not registered at all. Explicitly requested: say so. Left to the
+                // default (every eligible provider): simply not eligible, so its
+                // slot is omitted rather than inventing a refusal for a provider
+                // nobody wired up.
+                if (ask.providers === undefined)
+                    return null;
+                return [providerId, { status: 'refused', kind: 'could-not-ask', reason: `no "${providerId}" carrier is registered` }];
+            }
+            const slot = await resolveProviderSlot({
+                ask,
+                providerId,
+                carrier,
+                cache: context.cache,
+                singleFlight: context.singleFlight,
+                now: context.now,
+                localAskDeadlineMs: context.localAskDeadlineMs,
+                stats: context.stats,
+            });
+            return [providerId, slot];
+        }));
+        const providers = {};
+        for (const entry of slotEntries) {
+            if (entry === null)
+                continue;
+            const [providerId, slot] = entry;
+            providers[providerId] = slot;
+        }
+        answers.push({ providers });
+    }
+    return { answers };
+};
+// ---------------------------------------------------------------------------
+// Refused-could-not-ask: fallback: 'none', or a service that stays down
+// ---------------------------------------------------------------------------
+const refusedCouldNotAskResponse = (asks, reason) => ({
+    answers: asks.map((ask) => {
+        const providers = {};
+        for (const providerId of ask.providers ?? ALL_PROVIDER_IDS) {
+            providers[providerId] = { status: 'refused', kind: 'could-not-ask', reason };
+        }
+        return { providers };
+    }),
+});
+// ---------------------------------------------------------------------------
+// createQuoteClient
+// ---------------------------------------------------------------------------
+/**
+ * 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 const createQuoteClient = (config, options = {}) => {
+    const fetchImpl = config.fetch ?? fetch;
+    const now = config.now ?? Date.now;
+    const localAskDeadlineMs = options.localAskDeadlineMs ?? DEFAULT_LOCAL_ASK_DEADLINE_MS;
+    const cache = createAnswerCache({
+        ttlMs: config.cache?.ttlMs,
+        maxEntries: config.cache?.maxEntries,
+        now,
+        chainListRefreshStamp: options.chainListRefreshStamp,
+    });
+    const singleFlight = createSingleFlightGroup();
+    const configuredKeys = [
+        config.providers?.lifi?.apiKey,
+        config.providers?.relay?.apiKey,
+        config.providers?.nearIntents?.apiKey,
+    ].filter((key) => typeof key === 'string' && key !== '');
+    const funnel = options.funnel ??
+        createUpstreamFunnel({
+            neverSendChainIds: config.neverSendChainIds,
+            keys: configuredKeys,
+            concurrencyByCarrier: config.limits?.concurrencyByCarrier,
+            defaultRetryAfterMs: config.limits?.defaultRetryAfterMs,
+            fetch: fetchImpl,
+            now,
+        });
+    const carriers = (options.carriers ?? []).map((carrier) => funnel.wrap(carrier));
+    // `statsSnapshot`'s own counters — see `QuoteClientStatsRecorder`. Cache
+    // hit/miss/joined counts are this client's own, since only `client.ts`
+    // knows which of the three happened; the rate-limit and queue-depth
+    // figures are read live off `funnel` itself (see `upstream.ts`) rather
+    // than duplicated here, so there is exactly one place either can drift.
+    let hitCount = 0;
+    let missCount = 0;
+    let joinedCount = 0;
+    const upstreamCallsByCarrier = {};
+    const statsRecorder = {
+        recordCacheHit: () => {
+            hitCount += 1;
+        },
+        recordCacheMiss: () => {
+            missCount += 1;
+        },
+        recordCacheJoined: () => {
+            joinedCount += 1;
+        },
+        recordUpstreamCall: (providerId) => {
+            upstreamCallsByCarrier[providerId] = (upstreamCallsByCarrier[providerId] ?? 0) + 1;
+        },
+    };
+    // The breaker `docs/quote-service.md`'s "Decisions" section names: once a
+    // `serviceUrl` call fails under `fallback: 'direct'`, every call for the
+    // next 60 s skips straight to local mode rather than trying — and failing
+    // against — the service again.
+    let serviceUnavailableUntilMs = null;
+    const callService = async (asks) => {
+        // `config.serviceUrl` is only read inside this function, itself only
+        // called once `config.serviceUrl !== undefined` has already been
+        // checked by the caller — see `displayQuotes` below.
+        const url = `${config.serviceUrl.replace(/\/+$/, '')}/v1/display-quotes`;
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ asks }),
+            });
+        }
+        catch {
+            return { ok: false };
+        }
+        // A NON-2xx, OR AN UNREADABLE BODY, IS TREATED THE SAME AS UNREACHABLE.
+        // `docs/quote-service.md`'s "Decisions" section names network error, 5xx
+        // and 403 explicitly; any other status this service should never answer
+        // with (400, 404, ...) means a caller cannot use the response either
+        // way, so it is folded into the same fallback path rather than left to
+        // throw — a display-quote surface degrading to "could not ask" beats one
+        // that throws on an upstream's unexpected day.
+        if (!response.ok)
+            return { ok: false };
+        const body = await response.json().catch(() => null);
+        const parsed = displayQuoteResponseSchema.safeParse(body);
+        if (!parsed.success)
+            return { ok: false };
+        return { ok: true, response: parsed.data };
+    };
+    return {
+        displayQuotes: async (rawRequest) => {
+            const { asks } = displayQuoteRequestSchema.parse(rawRequest);
+            if (config.serviceUrl === undefined) {
+                return runLocally(asks, { carriers, cache, singleFlight, now, localAskDeadlineMs, stats: statsRecorder });
+            }
+            const breakerActive = config.fallback === 'direct' && serviceUnavailableUntilMs !== null && now() < serviceUnavailableUntilMs;
+            if (!breakerActive) {
+                const outcome = await callService(asks);
+                if (outcome.ok) {
+                    serviceUnavailableUntilMs = null;
+                    return outcome.response;
+                }
+                if (config.fallback === 'direct') {
+                    serviceUnavailableUntilMs = now() + SERVICE_BREAKER_MS;
+                }
+            }
+            if (config.fallback === 'none') {
+                return refusedCouldNotAskResponse(asks, 'the quote service could not be reached');
+            }
+            return runLocally(asks, { carriers, cache, singleFlight, now, localAskDeadlineMs, stats: statsRecorder });
+        },
+        statsSnapshot: () => ({
+            hits: hitCount,
+            misses: missCount,
+            joined: joinedCount,
+            upstreamCallsByCarrier: { ...upstreamCallsByCarrier },
+            rateLimited429s: funnel.rateLimited429Count(),
+            queueDepth: funnel.queueDepth(),
+        }),
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@gibs/quotes` — the isomorphic core for asking cross-chain bridge
+ * aggregators for display and execution quotes. See `docs/quote-service.md`'s
+ * "Library" section for the three ways a host builds a client from this
+ * package, and the per-module files for everything this barrel re-exports.
+ */
+export * from './quote-service-contract.js';
+export * from './quote-refusals.js';
+export * from './quote-guards.js';
+export * from './cache.js';
+export * from './single-flight.js';
+export * from './client.js';
+export * from './upstream.js';
+export * from './chain-lists.js';
+export * from './carriers/lifi.js';
+export * from './carriers/relay.js';
+export * from './carriers/near-intents.js';
+export * from './search/index.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * `@gibs/quotes` — the isomorphic core for asking cross-chain bridge
+ * aggregators for display and execution quotes. See `docs/quote-service.md`'s
+ * "Library" section for the three ways a host builds a client from this
+ * package, and the per-module files for everything this barrel re-exports.
+ */
+export * from './quote-service-contract.js';
+export * from './quote-refusals.js';
+export * from './quote-guards.js';
+export * from './cache.js';
+export * from './single-flight.js';
+export * from './client.js';
+export * from './upstream.js';
+export * from './chain-lists.js';
+export * from './carriers/lifi.js';
+export * from './carriers/relay.js';
+export * from './carriers/near-intents.js';
+export * from './search/index.js';

package/dist/quote-guards.d.ts

@@ -0,0 +1,128 @@
+import type { ProviderId } from '@gibs/bridge-sdk/providers';
+import { type DisplayAsk } from './quote-service-contract.js';
+/**
+ * The shared upstream guards `docs/quote-service.md`'s "Guards" and "Cache"
+ * sections name: a keyed concurrency limiter with a deadline, a Retry-After
+ * cooldown, the display-quote cache key, and the bigint scaling formula. A
+ * host wraps every network call to a provider through these before it ever
+ * reaches `fetch` — see `types.ts`'s `UpstreamFunnel`.
+ */
+/**
+ * Thrown by {@link KeyedConcurrencyLimiter.run} when a slot under `key` does
+ * not open before the caller's deadline. The task is never started — a host
+ * catches this and answers `could-not-ask: busy` (`docs/quote-service.md`'s
+ * "Guards" section) rather than queuing indefinitely behind a saturated
+ * provider.
+ */
+export declare class ConcurrencyDeadlineExceededError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+/** Caps how many tasks registered under the same key run at once. */
+export type KeyedConcurrencyLimiter = {
+    /**
+     * Runs `task` once fewer than `limit` tasks are already active under
+     * `key`, queuing FIFO otherwise.
+     *
+     * @param key - the concurrency bucket (a provider id, a carrier id, ...)
+     * @param limit - the most tasks that may run under `key` at once
+     * @param task - the work to run once a slot is free
+     * @param options.deadlineMs - epoch milliseconds after which a still-queued
+     *   task rejects with {@link ConcurrencyDeadlineExceededError} instead of
+     *   running. Omitted means "wait indefinitely," matching the query-layer
+     *   caller that has no deadline of its own.
+     * @param options.now - the clock; defaults to `Date.now`, overridable for a test
+     * @returns whatever `task` resolves to
+     * @throws {ConcurrencyDeadlineExceededError} when the deadline passes first
+     */
+    readonly run: <Value>(key: string, limit: number, task: () => Promise<Value>, options?: {
+        readonly deadlineMs?: number;
+        readonly now?: () => number;
+    }) => Promise<Value>;
+    /**
+     * How many tasks are queued FIFO right now, waiting for a slot — across
+     * every key, or (with `key`) one key alone. A task already running counts
+     * toward `limit`, never toward this: it answers "how many are waiting,"
+     * the figure `/stats`'s `queueDepth` reports, per `docs/quote-service.md`'s
+     * "Endpoint" section.
+     *
+     * @param key - narrows to one concurrency bucket; omitted sums every key
+     * @returns the queued count
+     */
+    readonly queueDepth: (key?: string) => number;
+};
+/**
+ * Builds a fresh, empty {@link KeyedConcurrencyLimiter}.
+ *
+ * @returns the limiter
+ */
+export declare const createKeyedConcurrencyLimiter: () => KeyedConcurrencyLimiter;
+/** How long a key is treated as rate-limited when its answer carries no readable `Retry-After`. */
+export declare const DEFAULT_RETRY_AFTER_COOLDOWN_MS = 30000;
+/** Tracks per-key `429`/`Retry-After` cooldowns, so a key is asked again only once its own cooldown has passed. */
+export type RetryAfterCooldown = {
+    /**
+     * Records that `key` answered `429` (or any rate-limited status) just now,
+     * so it is treated as cooling down until the cooldown
+     * {@link backoffMsFromRetryAfter} derives from `retryAfterHeader` elapses.
+     *
+     * @param key - the provider or carrier that answered rate-limited
+     * @param retryAfterHeader - the response's `Retry-After` header value, or null
+     * @param nowMs - the current time in epoch milliseconds; defaults to `Date.now()`
+     */
+    readonly record: (key: string, retryAfterHeader: string | null, nowMs?: number) => void;
+    /**
+     * Whether `key` is still inside a cooldown {@link record} started.
+     *
+     * @param key - the key under consideration
+     * @param nowMs - the current time in epoch milliseconds; defaults to `Date.now()`
+     * @returns whether a call under this key should be skipped for now
+     */
+    readonly isActive: (key: string, nowMs?: number) => boolean;
+    /**
+     * The cooldown's own deadline for `key`, in epoch milliseconds, or null
+     * when none is recorded — the figure a `could-not-ask: busy` /
+     * `retryAfterMs` answer is computed from.
+     *
+     * @param key - the key under consideration
+     * @returns the epoch millisecond the cooldown clears, or null
+     */
+    readonly clearsAtMs: (key: string) => number | null;
+    /** Clears every recorded cooldown. Test-only. */
+    readonly reset: () => void;
+};
+/**
+ * Builds a fresh, empty {@link RetryAfterCooldown}.
+ *
+ * @param options.defaultMs - the fallback cooldown; defaults to
+ *   {@link DEFAULT_RETRY_AFTER_COOLDOWN_MS}
+ * @returns the cooldown tracker
+ */
+export declare const createRetryAfterCooldown: (options?: {
+    readonly defaultMs?: number;
+}) => RetryAfterCooldown;
+/**
+ * Builds the display-quote cache key for one provider's answer to one ask,
+ * exactly per `docs/quote-service.md`'s "Cache" section:
+ * `v1|provider|from.chainId|from.token|to.chainId|to.token|recipientEcosystem|probeSetVersion|bucket`.
+ *
+ * @param provider - which provider this key caches an answer for
+ * @param ask - the ask being cached; only the fields the key is built from
+ * @param probeSetVersion - the server's own probe-address generation, so a
+ *   rotated probe address never serves a cached answer keyed to the old one
+ * @returns the cache key
+ */
+export declare const displayQuoteCacheKey: (provider: ProviderId, ask: Pick<DisplayAsk, "from" | "to" | "amount" | "recipientEcosystem">, probeSetVersion: string) => string;
+/**
+ * Scales a cached figure — answered for a NEARBY amount — into an estimate
+ * for the amount actually asked, per `docs/quote-service.md`'s "Cache"
+ * section: `scaled = figure × userAmount / askedAmount`, entirely in bigint.
+ *
+ * @param figure - the nearby amount's own raw answer
+ * @param userAmount - the amount actually asked for (this asker's own amount)
+ * @param askedAmount - the amount that was actually asked upstream (the
+ *   nearby, cached amount `figure` answers)
+ * @returns the scaled estimate, in the same units as `figure`
+ * @throws when `askedAmount` is not positive — there is nothing to scale from
+ */
+export declare const scaleToAskedAmount: (figure: bigint, userAmount: bigint, askedAmount: bigint) => bigint;