@gibs/quotes 1.13.0

package/dist/upstream.js

@@ -0,0 +1,343 @@
+import { isLifiInvalidApiKeyResponse } from './quote-refusals.js';
+import { ConcurrencyDeadlineExceededError, createKeyedConcurrencyLimiter, createRetryAfterCooldown, } from './quote-guards.js';
+/**
+ * The single choke point every outbound network call a {@link Carrier} makes
+ * passes through — see `docs/quote-service.md`'s "Carriers" section for the
+ * narrative and `types.ts`'s {@link UpstreamFunnel} for the contract this
+ * module implements.
+ *
+ * TWO LAYERS, BECAUSE `Carrier.ask` HIDES THE WIRE. `UpstreamFunnel.wrap`
+ * only sees a {@link CarrierAskRequest} (an edge and an amount) and a
+ * {@link CarrierAskAnswer} (delivered/refusal) — never a URL, a request body,
+ * or a response header, because that is exactly what makes `Carrier` usable
+ * for a free local read as well as a network call. The guards this module
+ * must enforce — the Retry-After cooldown, the 401-code-1010 breaker, and
+ * the chain tripwire's URL/body scan — all need that wire-level view. So
+ * this module builds it in two pieces:
+ *
+ * - {@link createUpstreamFunnel}'s `wrap` applies the STRUCTURAL guards every
+ *   `Carrier.ask` call can be judged on without touching the network: the
+ *   chain-id tripwire read off the edge itself, the per-carrier concurrency
+ *   cap, and refusing locally while a carrier's cooldown is active.
+ * - Its `guardedFetch` is the WIRE-level guard: every built-in carrier
+ *   (`carriers/lifi.ts`, `carriers/relay.ts`, `carriers/near-intents.ts`)
+ *   must call it — bound to its own {@link CarrierId} — instead of calling
+ *   `fetch` directly. It re-runs the chain tripwire against the actual
+ *   outgoing URL and body (the backstop `docs/quote-service.md` calls for:
+ *   "rejects any 369/943 in the address or body"), records a `429`'s
+ *   `Retry-After` into the SAME cooldown `wrap` reads, and — for `'lifi'`
+ *   only — arms the five-minute breaker on a `401` carrying LI.FI's
+ *   `code: 1010`.
+ *
+ * A caller wires the two together: build the funnel first, construct each
+ * carrier with `(input, init) => funnel.guardedFetch(carrierId, input, init)`
+ * as its `fetchImpl`, THEN call `funnel.wrap(carrier)` on the result. Skipping
+ * either half leaves a real gap — `wrap` alone never sees a 429 to cool down
+ * from, and `guardedFetch` alone never caps concurrency.
+ */
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+/** Every built-in carrier's own concurrency cap, unless `concurrencyByCarrier` overrides it. */
+export const DEFAULT_CARRIER_CONCURRENCY = 4;
+/** NEAR Intents' own default concurrency cap — see `docs/quote-service.md`'s "Guards" section: "4, NEAR 3." */
+export const NEAR_INTENTS_CONCURRENCY = 3;
+/** Per-provider defaults, read when `concurrencyByCarrier` names no override for a carrier. */
+export const DEFAULT_CONCURRENCY_BY_CARRIER = {
+    lifi: DEFAULT_CARRIER_CONCURRENCY,
+    relay: DEFAULT_CARRIER_CONCURRENCY,
+    'near-intents': NEAR_INTENTS_CONCURRENCY,
+};
+/** How long the LI.FI carrier is refused after a `401` carrying `code: 1010` — five minutes, per `docs/quote-service.md`'s "Cache" section. */
+export const LIFI_INVALID_API_KEY_BREAKER_MS = 5 * 60_000;
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+/**
+ * Thrown by {@link GuardedFetch} BEFORE any network call, when the outgoing
+ * request names a chain id the host listed in `neverSendChainIds` — either in
+ * a query parameter or inside the JSON body, under one of the structured
+ * chain-id field names this module reads (never a raw string search over the
+ * whole request, which would also match an amount or an address that merely
+ * CONTAINS the digits).
+ */
+export class NeverSendChainIdError extends Error {
+    chainId;
+    carrierId;
+    constructor(chainId, carrierId) {
+        super(`refusing to ask "${carrierId}" about chain ${chainId}: it is on this host's neverSendChainIds`);
+        this.chainId = chainId;
+        this.carrierId = carrierId;
+        this.name = 'NeverSendChainIdError';
+    }
+}
+/**
+ * Thrown by {@link GuardedFetch} when a configured provider key would
+ * otherwise appear in the outgoing URL or body — `docs/quote-service.md`'s
+ * rule, "keys go only into headers, never URLs or bodies, never logs,"
+ * enforced rather than merely documented.
+ */
+export class KeyLeakError extends Error {
+    carrierId;
+    constructor(carrierId) {
+        super(`refusing to send "${carrierId}"'s request: a configured key appears in the URL or body`);
+        this.carrierId = carrierId;
+        this.name = 'KeyLeakError';
+    }
+}
+/**
+ * Thrown by {@link GuardedFetch} for `'lifi'` while its five-minute breaker
+ * is active — see {@link LIFI_INVALID_API_KEY_BREAKER_MS}. Never thrown for
+ * any other carrier; only LI.FI answers a rejected key with a 401 this
+ * module can classify (`isLifiInvalidApiKeyResponse`).
+ */
+export class LifiApiKeyBreakerActiveError extends Error {
+    constructor() {
+        super('refusing to ask "lifi": the configured api key was rejected within the last five minutes');
+        this.name = 'LifiApiKeyBreakerActiveError';
+    }
+}
+// ---------------------------------------------------------------------------
+// The chain-id tripwire — structured fields only, never a raw string search
+// ---------------------------------------------------------------------------
+/** Query-parameter names a provider's `GET` request names a chain id under. */
+const CHAIN_ID_QUERY_PARAM_NAMES = new Set([
+    'fromChain',
+    'toChain',
+    'originChainId',
+    'destinationChainId',
+    'chainId',
+]);
+/** JSON body key names a provider's request names a chain id under. */
+const CHAIN_ID_BODY_KEY_NAMES = new Set([
+    'fromChainId',
+    'toChainId',
+    'originChainId',
+    'destinationChainId',
+    'chainId',
+]);
+/**
+ * Reads every value found under a known chain-id query-parameter name.
+ *
+ * @param url - the outgoing request's URL
+ * @returns every chain id the query string structurally names
+ */
+const chainIdsFromQuery = (url) => {
+    const found = [];
+    for (const [key, value] of url.searchParams) {
+        if (!CHAIN_ID_QUERY_PARAM_NAMES.has(key))
+            continue;
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            found.push(parsed);
+    }
+    return found;
+};
+/**
+ * Recursively reads every value found under a known chain-id JSON body key,
+ * at any depth. Every OTHER field — an amount, an address, a slippage
+ * fraction — is walked past without being read, which is what keeps an
+ * amount that happens to contain a guarded chain id's digits (`"369"` inside
+ * `"36900000"`) from ever being mistaken for one.
+ *
+ * @param value - the parsed JSON body, or a nested part of it
+ * @param found - collects every chain id found, by mutation
+ */
+const collectChainIdsFromBody = (value, found) => {
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            collectChainIdsFromBody(entry, found);
+        return;
+    }
+    if (typeof value !== 'object' || value === null)
+        return;
+    for (const [key, entryValue] of Object.entries(value)) {
+        if (CHAIN_ID_BODY_KEY_NAMES.has(key)) {
+            if (typeof entryValue === 'number' && Number.isFinite(entryValue)) {
+                found.push(entryValue);
+            }
+            else if (typeof entryValue === 'string' && /^\d+$/.test(entryValue)) {
+                found.push(Number(entryValue));
+            }
+        }
+        collectChainIdsFromBody(entryValue, found);
+    }
+};
+/**
+ * Every chain id a request structurally names, from its URL and its JSON
+ * body — the set {@link GuardedFetch} checks against `neverSendChainIds`
+ * before ever calling `fetch`.
+ *
+ * @param url - the outgoing request's URL
+ * @param body - the outgoing request's raw body, when it has one
+ * @returns every chain id named in a recognized field
+ */
+const namedChainIds = (url, body) => {
+    const found = new Set(chainIdsFromQuery(url));
+    if (body === undefined)
+        return found;
+    let parsedBody;
+    try {
+        parsedBody = JSON.parse(body);
+    }
+    catch {
+        // Not a JSON body — nothing structured left to read.
+        return found;
+    }
+    const collected = [];
+    collectChainIdsFromBody(parsedBody, collected);
+    for (const id of collected)
+        found.add(id);
+    return found;
+};
+const buildGuardedFetch = (options) => {
+    const { neverSendChainIds, keys, retryAfterCooldown, lifiKeyBreaker, fetchImpl, now, onRateLimited } = options;
+    return async (carrierId, input, init) => {
+        const url = new URL(typeof input === 'string' ? input : input.toString());
+        const body = typeof init?.body === 'string' ? init.body : undefined;
+        for (const chainId of namedChainIds(url, body)) {
+            if (neverSendChainIds.has(chainId)) {
+                throw new NeverSendChainIdError(chainId, carrierId);
+            }
+        }
+        const urlAndBody = `${url.toString()}\u0000${body ?? ''}`;
+        for (const key of keys) {
+            if (key !== '' && urlAndBody.includes(key)) {
+                throw new KeyLeakError(carrierId);
+            }
+        }
+        if (carrierId === 'lifi' && lifiKeyBreaker.isActive('lifi', now())) {
+            throw new LifiApiKeyBreakerActiveError();
+        }
+        const response = await fetchImpl(url.toString(), init);
+        if (response.status === 429) {
+            retryAfterCooldown.record(carrierId, response.headers.get('retry-after'), now());
+            onRateLimited();
+        }
+        if (carrierId === 'lifi' && response.status === 401) {
+            const body401 = await response
+                .clone()
+                .json()
+                .catch(() => null);
+            if (isLifiInvalidApiKeyResponse(response.status, body401)) {
+                // Logged loudly by the host — this module only classifies and arms
+                // the breaker; see `quote-refusals.ts`'s own note on why a rejected
+                // key is never silently absorbed here.
+                lifiKeyBreaker.record('lifi', null, now());
+            }
+        }
+        return response;
+    };
+};
+// ---------------------------------------------------------------------------
+// wrap — the structural half every Carrier.ask goes through
+// ---------------------------------------------------------------------------
+/**
+ * The chain-id tripwire's STRUCTURAL half, read straight off the edge a
+ * carrier was asked about — applies to EVERY carrier, rate-limited or not,
+ * per `types.ts`'s own note: "a local read that happened to be pointed at a
+ * guarded chain is exactly as dangerous as a network call to one." This runs
+ * BEFORE the carrier's own `ask`, so a free local read never even starts
+ * when its edge names a guarded chain.
+ *
+ * @param ask - the carrier's own `ask`
+ * @param carrierId - the carrier's own id, for the refusal's `reason`
+ * @param neverSendChainIds - the host's guarded chain ids
+ * @returns a wrapped `ask` that refuses `cannot-carry` before calling through
+ */
+const chainGuardedAsk = (ask, carrierId, neverSendChainIds) => {
+    return async (request) => {
+        const guardedChainId = [request.edge.from.chainId, request.edge.to.chainId].find((chainId) => neverSendChainIds.has(chainId));
+        if (guardedChainId !== undefined) {
+            return {
+                ok: false,
+                refusal: {
+                    kind: 'cannot-carry',
+                    reason: `chain ${guardedChainId} is on this host's neverSendChainIds`,
+                    minimumAmount: null,
+                },
+            };
+        }
+        return ask(request);
+    };
+};
+/**
+ * Builds the funnel every carrier's `ask` — built-in or host-registered —
+ * should be wrapped through, and the wire-level {@link GuardedFetch} every
+ * built-in carrier's own HTTP call should go through. See this module's
+ * head note for how the two fit together.
+ *
+ * @param options - see {@link CreateUpstreamFunnelOptions}
+ * @returns the funnel
+ */
+export const createUpstreamFunnel = (options = {}) => {
+    const neverSendChainIds = new Set(options.neverSendChainIds ?? []);
+    const keys = (options.keys ?? []).filter((key) => key !== '');
+    const concurrencyLimiter = createKeyedConcurrencyLimiter();
+    const retryAfterCooldown = createRetryAfterCooldown(options.defaultRetryAfterMs === undefined ? {} : { defaultMs: options.defaultRetryAfterMs });
+    const lifiKeyBreaker = createRetryAfterCooldown({ defaultMs: LIFI_INVALID_API_KEY_BREAKER_MS });
+    const fetchImpl = options.fetch ?? fetch;
+    const now = options.now ?? Date.now;
+    let rateLimited429Count = 0;
+    const guardedFetch = buildGuardedFetch({
+        neverSendChainIds,
+        keys,
+        retryAfterCooldown,
+        lifiKeyBreaker,
+        fetchImpl,
+        now,
+        onRateLimited: () => {
+            rateLimited429Count += 1;
+        },
+    });
+    const concurrencyLimitFor = (carrier) => options.concurrencyByCarrier?.[carrier.id] ??
+        carrier.concurrencyLimit ??
+        DEFAULT_CONCURRENCY_BY_CARRIER[carrier.id] ??
+        DEFAULT_CARRIER_CONCURRENCY;
+    return {
+        guardedFetch,
+        rateLimited429Count: () => rateLimited429Count,
+        queueDepth: () => concurrencyLimiter.queueDepth(),
+        wrap: (carrier) => {
+            const chainGuarded = chainGuardedAsk(carrier.ask, carrier.id, neverSendChainIds);
+            if (!carrier.isRateLimited) {
+                // A FREE CARRIER IS RETURNED UNCHANGED but for the chain guard —
+                // see `types.ts`'s own note on `UpstreamFunnel`.
+                return { ...carrier, ask: chainGuarded };
+            }
+            const limit = concurrencyLimitFor(carrier);
+            const guardedAsk = async (request) => {
+                const nowMs = now();
+                if (retryAfterCooldown.isActive(carrier.id, nowMs)) {
+                    const clearsAtMs = retryAfterCooldown.clearsAtMs(carrier.id);
+                    return {
+                        ok: false,
+                        refusal: {
+                            kind: 'could-not-ask',
+                            reason: clearsAtMs === null
+                                ? 'cooling down after a rate limit'
+                                : `cooling down after a rate limit until ${new Date(clearsAtMs).toISOString()}`,
+                            minimumAmount: null,
+                        },
+                    };
+                }
+                try {
+                    return await concurrencyLimiter.run(carrier.id, limit, () => chainGuarded(request), {
+                        now,
+                        ...(options.askDeadlineMs === undefined ? {} : { deadlineMs: nowMs + options.askDeadlineMs }),
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ConcurrencyDeadlineExceededError) {
+                        return {
+                            ok: false,
+                            refusal: { kind: 'could-not-ask', reason: 'busy', minimumAmount: null },
+                        };
+                    }
+                    throw error;
+                }
+            };
+            return { ...carrier, ask: guardedAsk };
+        },
+    };
+};

package/llms.txt

@@ -0,0 +1,217 @@
+# Cross-Chain Quote Client
+
+> An isomorphic TypeScript library that asks several cross-chain bridge
+> aggregators for live quotes at once, merges the answers, and helps you
+> route a transfer for the best delivered amount at the fewest wallet
+> signatures. It runs unchanged in a browser tab or on a Node server. It
+> carries no host name, no chain policy, and no secret of its own — you
+> supply all three through one configuration object.
+
+## Quick orientation
+
+- This package runs in three modes: **from your own backend** (with real
+  provider keys), **straight from a browser** (with no secret, or a public
+  identifier only), or **against your own hosted quote service, with a
+  browser fallback**. Pick one mode below and use its configuration shape.
+- The wire contract below (`POST /v1/display-quotes`) is what a hosted
+  quote service and a direct-from-browser client both speak. If you run
+  your own service with the server-side pieces of this package, your
+  server and your browser client already agree on the same request and
+  response shapes.
+- A short list of rules never bend. Read them before you build anything
+  that signs a transaction from a quote this library returns.
+
+## Install
+
+Add the package as a dependency with your usual package manager, then
+import from its root:
+
+```ts
+import { createQuoteClient, type QuoteClientConfig } from '<this-package>'
+```
+
+Replace `<this-package>` with the name you installed this under — you
+already know it from your own `package.json` dependency entry.
+
+## Configuration: `QuoteClientConfig`
+
+Every fact about who is asking — provider keys, allowed origins, chain
+policy — lives in one object. Nothing else in this library carries a
+default that assumes a particular deployment.
+
+```ts
+type QuoteClientConfig = {
+  providers?: {
+    lifi?: { apiKey?: string; integrator?: string; baseUrl?: string; fee?: number }
+    relay?: { apiKey?: string; referrer?: string; baseUrl?: string }
+    nearIntents?: { apiKey?: string; referral?: string; baseUrl?: string }
+  }
+  serviceUrl?: string
+  fallback: 'direct' | 'none'
+  probeAddresses?: Partial<Record<Ecosystem, string>>
+  neverSendChainIds?: readonly number[]
+  cache?: { ttlMs?: number; maxEntries?: number }
+  limits?: { concurrencyByCarrier?: Record<string, number>; defaultRetryAfterMs?: number }
+  fetch?: typeof fetch
+  now?: () => number
+}
+```
+
+`fallback` is required on purpose. Every caller states what happens when
+`serviceUrl` cannot be reached, instead of inheriting a silent default.
+
+## Mode 1: your own backend, with real secrets
+
+Run this on a server you control. Provider keys stay on that server and
+are never sent to a browser.
+
+```ts
+const client = createQuoteClient(
+  {
+    providers: {
+      lifi: { apiKey: process.env.LIFI_API_KEY, integrator: 'your-app' },
+      relay: { apiKey: process.env.RELAY_API_KEY },
+    },
+    fallback: 'none',
+    neverSendChainIds: [/* any chain id your own bridge must never expose to an aggregator */],
+  },
+  { carriers: [/* built-in and/or your own Carrier implementations — see below */] },
+)
+
+const response = await client.displayQuotes({ asks: [/* ... */] })
+```
+
+## Mode 2: straight from the browser, no service
+
+Send no secret to the browser. Omit every `providers.*.apiKey`, or send
+only a public, rate-limit-budget identifier — the same way a browser-safe
+value already works today. Leave `serviceUrl` unset.
+
+```ts
+const client = createQuoteClient(
+  {
+    providers: { relay: { referrer: 'your-app.example' } },
+    fallback: 'none',
+  },
+  { carriers: [/* your carriers */] },
+)
+```
+
+Every request this client makes goes straight from the visitor's browser
+to each provider.
+
+## Mode 3: your own hosted service, with a browser fallback
+
+Point the browser at a service you run — built from this same package's
+server-side pieces — and fall back to Mode 2 automatically when that
+service cannot be reached.
+
+```ts
+const client = createQuoteClient({
+  serviceUrl: 'https://quotes.your-app.example',
+  fallback: 'direct',
+  providers: { relay: { referrer: 'your-app.example' } }, // used only during a fallback
+})
+```
+
+`fallback: 'direct'` opens a 60-second breaker after one failed call to
+`serviceUrl`, so a flapping service does not fail every single request on
+its way down; `fallback: 'none'` instead answers every ask with a
+`could-not-ask` refusal and never falls back to a direct call.
+
+## Wire contract: `POST /v1/display-quotes`
+
+If you run your own service (Mode 3), have it answer this exact shape —
+the browser client this package builds already speaks it.
+
+Request body: `{ "asks": DisplayAsk[] }`, 1 to 24 asks, answered in order.
+
+```ts
+type DisplayAsk = {
+  from: { chainId: number; token: string }
+  to: { chainId: number; token: string }
+  amount: string          // decimal string, base units of from.token
+  recipientEcosystem?: 'evm' | 'svm' | 'bvm' | 'tvm' | 'tonvm' | 'hypevm' | 'zcash' // default: derived from to.chainId
+  providers?: ('lifi' | 'relay' | 'near-intents')[]  // default: every eligible provider
+  precision?: 'estimate-ok' | 'exact'  // default: 'estimate-ok'
+}
+```
+
+Response: `{ "answers": [{ "providers": { lifi?, relay?, "near-intents"? } }] }`,
+one answer per ask, in ask order. Each provider slot is one of three
+shapes:
+
+- **`quoted`** — `basis: 'exact'` or `basis: 'scaled-from-nearby-amount'`,
+  plus `askedAmount`, `expectedAmount`, an optional `minimumAmount`,
+  `quotedAt`, `ageMs`, and `cache: 'miss' | 'hit' | 'joined'`. A
+  `scaled-from-nearby-amount` answer also carries `scaledFrom`: the real
+  amount and the real answer it was scaled from.
+- **`refused`** — `kind: 'no-quote' | 'could-not-ask' | 'cannot-carry' | 'invalid-api-key'`,
+  a `reason` (or null), and `minimumAmount` when the provider named one.
+- **`pending`** — the provider's own call is still running. Retry after
+  `retryAfterMs`. The call keeps running in the background and fills the
+  cache for the next ask that asks the same question.
+
+`precision: 'exact'` asks for a genuine answer to the exact amount you
+asked for. It never accepts a scaled answer — see "Rules that never
+bend," below.
+
+## Route search: carriers
+
+The route-search engine asks every registered *carrier* — a built-in
+aggregator (LI.FI, Relay, NEAR Intents) or a local read you register
+yourself (a direct on-chain swap, your own bridge contract) — what it can
+deliver, then scores every combination it can build for the best
+delivered amount at the fewest wallet signatures.
+
+Register your own carrier by implementing the `Carrier` interface:
+
+```ts
+const myOwnCarrier: Carrier = {
+  id: 'my-carrier',
+  edgesFrom: (from, to) => [/* every edge this carrier can move funds across right now */],
+  isRateLimited: false, // true for anything that calls a rate-limited network API
+  ask: async ({ edge, inputAmount }) => {
+    // return { ok: true, deliveredAmount, minimumDeliveredAmount } or
+    //        { ok: false, refusal: { kind, reason, minimumAmount } }
+  },
+  // fusesWithNext?: (nextHop) => boolean — set this only when arriving via
+  // this carrier ALSO executes the next hop, so the two cost one signature.
+}
+```
+
+"Fewest signatures for the most delivered" is the engine's actual scoring
+order, not a slogan: it maximizes delivered amount first, then minimizes
+how many wallet signatures a route costs among routes that tie. A carrier
+that fuses two hops into a single signature beats an otherwise-equal route
+that costs an extra step.
+
+Every network call a carrier makes — built in or your own — passes
+through this library's shared guards (a keyed concurrency limiter, a
+Retry-After cooldown, and your `neverSendChainIds` tripwire) before it
+ever reaches `fetch`, once you wrap it through the client's upstream
+funnel.
+
+## Rules that never bend
+
+- **`neverSendChainIds` is enforced everywhere, including forwarding.** If
+  you run a chain that must never reach a public aggregator, name its id
+  here. Every outbound call this library makes, direct or forwarded,
+  refuses any request naming it.
+- **A binding quote is never cached or shared.** A quote that reserves a
+  real user address, real calldata, or a live deposit address answers
+  fresh every time — never from this library's own cache.
+- **A scaled figure never reaches an execution builder.** `expectedAmount`
+  and `minimumAmount` on a `basis: 'scaled-from-nearby-amount'` answer
+  carry a distinct type brand (`EstimatedDelivery`) from a genuine
+  `basis: 'exact'` answer (`ExactAmount`). The function that decodes an
+  amount for spending only accepts the exact brand, so mixing them up is a
+  compile error, not a rule you have to remember to check.
+- **Provider keys never run in a browser.** If your frontend needs a
+  display quote and you hold a real key, put it behind your own service
+  (Mode 3) — never Mode 2 with a real `apiKey` set on a browser build.
+- **Verify a route's execution calldata before signing it**, independent
+  of what a display quote showed. A display quote exists to show a reader
+  what to expect; it is never the thing that gets signed. Build and check
+  the real execution transaction separately, immediately before asking a
+  wallet to sign it.