@gibs/bridge-sdk 1.19.0 → 1.20.0

package/dist/origin-deposit.js

@@ -1,68 +1,12 @@
-/**
- * The ecosystem whose signer a deposit needs, or null for a deposit that needs
- * no signer at all.
- *
- * THE ONE PLACE THE ECOSYSTEM TAG IS READ. A {@link DepositAddressDeposit} has
- * no `ecosystem`, so every guard below asks through this instead of reading the
- * field directly — which also means no ecosystem guard can ever answer true for
- * a deposit the reader pays by hand.
- *
- * TYPED `Ecosystem | null`, NOT `string | null`. A `string` return let a typo
- * such as `signerEcosystemOf(deposit) === 'hypvm'` compile silently — the
- * comparison is just false forever, so `isHyperliquidDeposit` would always
- * answer false and every Hyperliquid deposit would fall through to the
- * Ethereum branch. Typed on the union, the same typo fails to compile instead.
- */
 const signerEcosystemOf = (deposit) => 'ecosystem' in deposit ? deposit.ecosystem : null;
 export const isEvmDeposit = (deposit) => signerEcosystemOf(deposit) === 'evm';
 export const isSolanaDeposit = (deposit) => signerEcosystemOf(deposit) === 'svm';
-/**
- * Narrows a Solana deposit to the instruction form, which must be compiled
- * before it can be signed.
- */
 export const isSolanaInstructionsDeposit = (deposit) => deposit.form === 'instructions';
-/**
- * Narrows a Solana deposit to the pre-compiled form, which must be signed
- * as-is.
- */
 export const isSolanaSerializedDeposit = (deposit) => deposit.form === 'serialized';
 export const isBitcoinDeposit = (deposit) => signerEcosystemOf(deposit) === 'bvm';
 export const isTronDeposit = (deposit) => signerEcosystemOf(deposit) === 'tvm';
 export const isTonDeposit = (deposit) => signerEcosystemOf(deposit) === 'tonvm';
 export const isHyperliquidDeposit = (deposit) => signerEcosystemOf(deposit) === 'hypevm';
-/**
- * Narrows a deposit to the pay-by-hand shape: an address, an amount, and
- * nothing to sign.
- *
- * THE GUARD EVERY EXECUTION PATH MUST ASK FIRST. A surface that falls through
- * to a signer with one of these has no transaction to give it, and a surface
- * that asks the reader to connect a wallet is asking for one that does not
- * exist for this chain.
- *
- * @param deposit - any origin deposit
- * @returns whether the reader pays this one by hand
- */
 export const isDepositAddressDeposit = (deposit) => 'kind' in deposit && deposit.kind === 'deposit-address';
-/**
- * Narrows a deposit to the priced-but-not-reserved shape: a route on display,
- * with nothing to pay until a live quote replaces it.
- *
- * @param deposit - any origin deposit
- * @returns whether the route must be quoted live before anything is paid
- */
 export const isUnreservedDeposit = (deposit) => 'kind' in deposit && deposit.kind === 'unreserved';
-/**
- * Names a deposit's family for a message shown to someone: its ecosystem, or
- * its `kind` for a deposit that has none — a {@link DepositAddressDeposit}
- * reads as `"deposit-address"`, an {@link UnreservedDeposit} as `"unreserved"`.
- *
- * THE ONE COPY. The same `'ecosystem' in deposit ? deposit.ecosystem :
- * deposit.kind` expression used to be written out separately in
- * `consolidated-quote.ts` and in the interface's `consolidated-execute.ts`;
- * each copy was a chance for the two to describe the same deposit
- * differently. Import this instead of restating the expression.
- *
- * @param deposit - any origin deposit
- * @returns the ecosystem name, or the deposit's `kind` when it has none
- */
 export const depositFamilyOf = (deposit) => 'ecosystem' in deposit ? deposit.ecosystem : deposit.kind;

package/dist/pre-quote.js

@@ -2,47 +2,12 @@ import { buildQuery } from '@gibs/common/url';
 import { isNonEthereumVirtualMachineOrigin, } from './consolidated-quote.js';
 import { resolveAttribution } from './referral.js';
 import { relayReferrerField, slippageToBasisPoints, } from './relay-quote.js';
-/**
- * Plain LI.FI swap quote endpoint (forward-solving), re-exported from
- * `consolidated-quote.js` rather than redeclared here — both modules must
- * agree on the same address, and a second literal would be free to drift from
- * it.
- */
 export { lifiQuoteUrl, lifiRequestHeaders } from './consolidated-quote.js';
-/**
- * Builds the Relay EXACT_INPUT swap pre-quote body for a fixed input. NO `txs`
- * are attached: Relay solves FORWARD and reports the delivered anchor amount.
- *
- * `recipient` and `refundTo` name TWO DIFFERENT chains and must never be
- * conflated. `refundTo` is always the user's OWN origin-chain address — Relay
- * refunds a failed (or, here, never-run) swap on the origin chain, and an
- * Ethereum fallback address could not receive one there. `recipient` names
- * where the swap lands on the ENTRY chain (`toChainId`), which is always
- * Ethereum Virtual Machine — for an Ethereum origin the user's own address
- * already satisfies that and is the default; for a non-Ethereum origin
- * (Solana base58, Bitcoin bech32, ...) it does NOT, and Relay's `/quote/v2`
- * validates the recipient's FORMAT against `toChainId` even though this
- * pre-quote never executes. Sending the origin account there — as an earlier
- * version of this builder did, reasoning that an unexecuted quote's recipient
- * is "informational" — gets Relay's `400 INVALID_ADDRESS` on every
- * non-Ethereum-origin pre-quote, which starves `fetchBestEntryAnchorPreQuote`
- * of its only capable provider and surfaces as "No route available" for the
- * whole non-Ethereum-origin flow. `request.recipient` (an explicit
- * Ethereum-format address the caller supplies) is therefore REQUIRED for a
- * non-Ethereum origin; without it this returns null.
- *
- * @param request - the provider-agnostic pre-quote request
- * @returns the request body, or null when the input amount is non-positive or
- *   a non-Ethereum origin has no explicit Ethereum-format `recipient`
- */
 export const buildRelayPreQuoteRequest = (request) => {
     if (request.amount <= 0n) {
         return null;
     }
     const nonEthereumOrigin = isNonEthereumVirtualMachineOrigin(request);
-    // A non-Ethereum origin's own address cannot stand in for an entry-chain
-    // recipient; it must be supplied explicitly. An Ethereum origin's own
-    // address already IS a valid entry-chain address, so it remains the default.
     const recipient = nonEthereumOrigin ? request.recipient : (request.recipient ?? request.fromAddress);
     if (recipient === undefined) {
         return null;
@@ -56,10 +21,6 @@ export const buildRelayPreQuoteRequest = (request) => {
         amount: request.amount.toString(),
         tradeType: 'EXACT_INPUT',
         recipient,
-        // Relay always refunds on the ORIGIN chain, so the origin's own address
-        // is the correct refund target regardless of ecosystem — unlike
-        // `recipient` above, this one is deliberately NOT Ethereum-format for a
-        // non-Ethereum origin.
         refundTo: request.fromAddress,
         ...relayReferrerField(request),
         ...(request.slippage === undefined
@@ -67,17 +28,6 @@ export const buildRelayPreQuoteRequest = (request) => {
             : { slippageTolerance: slippageToBasisPoints(request.slippage) }),
     };
 };
-/**
- * Builds the plain LI.FI swap pre-quote as a query string for `GET /v1/quote`.
- * LI.FI's plain `/quote` is forward-solving by construction (`fromAmount` in,
- * `estimate.toAmount` out), so no trade-type flag is needed.
- *
- * Returns null for a non-Ethereum origin (LI.FI cannot bridge across
- * virtual-machine ecosystems) and for a non-positive input amount.
- *
- * @param request - the provider-agnostic pre-quote request
- * @returns the URL query string (without a leading `?`), or null
- */
 export const buildLifiPreQuoteRequest = (request) => {
     if (request.amount <= 0n) {
         return null;
@@ -85,9 +35,6 @@ export const buildLifiPreQuoteRequest = (request) => {
     if (isNonEthereumVirtualMachineOrigin(request)) {
         return null;
     }
-    // Left out or `null` OMITS the query parameter (LI.FI's own schema marks it
-    // optional); a string is sent as-is. No package default: attribution is the
-    // caller's to choose. See `PreQuoteRequest.lifiIntegrator`'s doc.
     const integrator = resolveAttribution(request.lifiIntegrator, undefined);
     return buildQuery({
         fromChain: request.fromChainId.toString(),
@@ -96,7 +43,6 @@ export const buildLifiPreQuoteRequest = (request) => {
         toToken: request.toTokenAddress,
         fromAmount: request.amount.toString(),
         fromAddress: request.fromAddress,
-        // Each optional parameter is left out when it is undefined.
         integrator,
         slippage: request.slippage?.toString(),
     });
@@ -107,11 +53,6 @@ const asRecord = (value) => {
     }
     return value;
 };
-/**
- * Parses a decimal-string amount into a bigint.
- *
- * @returns the bigint value, or null when the input is not a parseable amount
- */
 const parseAmount = (value) => {
     if (typeof value !== 'string' || value === '') {
         return null;
@@ -123,13 +64,6 @@ const parseAmount = (value) => {
         return null;
     }
 };
-/**
- * Assembles the expected/minimum pair, defaulting the minimum to the expected
- * amount when the provider omits a guaranteed floor. Shared by both parsers so
- * the fallback rule lives in exactly one place.
- *
- * @returns the result, or null when the expected amount is absent
- */
 const toPreQuoteResult = (expected, minimum) => {
     const expectedAmount = parseAmount(expected);
     if (expectedAmount === null) {
@@ -141,13 +75,6 @@ const toPreQuoteResult = (expected, minimum) => {
         minimumAmount: minimumAmount ?? expectedAmount,
     };
 };
-/**
- * Parses a Relay EXACT_INPUT pre-quote response. The delivered anchor figures
- * live under `details.currencyOut`: `amount` (expected) and `minimumAmount`
- * (guaranteed slippage floor). Verified live against `api.relay.link/quote/v2`.
- *
- * @returns the delivered amounts, or null when the payload shape is unexpected
- */
 export const parseRelayPreQuote = (payload) => {
     const currencyOut = asRecord(asRecord(asRecord(payload)?.details)?.currencyOut);
     if (!currencyOut) {
@@ -155,13 +82,6 @@ export const parseRelayPreQuote = (payload) => {
     }
     return toPreQuoteResult(currencyOut.amount, currencyOut.minimumAmount);
 };
-/**
- * Parses a plain LI.FI `/quote` response. The delivered anchor figures live
- * under `estimate`: `toAmount` (expected) and `toAmountMin` (guaranteed minimum
- * after slippage) — the same estimate shape the route-step normalizer reads.
- *
- * @returns the delivered amounts, or null when the payload shape is unexpected
- */
 export const parseLifiPreQuote = (payload) => {
     const estimate = asRecord(asRecord(payload)?.estimate);
     if (!estimate) {

package/dist/prices.js

@@ -1,50 +1,15 @@
 import { formatUnits } from 'viem';
 import { Chains, nativeAssetOut, toChain } from './config.js';
-/**
- * PulseChain mainnet numeric chain id (`Chains.PLS` = `0x171`). Tokens on this
- * chain (and its testnet sibling below) are priced on-chain via PulseX rather
- * than from an off-chain price feed.
- */
 export const PULSECHAIN_CHAIN_ID = Number(Chains.PLS);
-/**
- * PulseChain V4 testnet numeric chain id (`Chains.V4PLS` = `0x3af`). Shares the
- * PulseX on-chain pricing path with mainnet.
- */
 export const PULSECHAIN_TESTNET_CHAIN_ID = Number(Chains.V4PLS);
-/**
- * Bridged DAI on PulseChain (18 decimals) — the USD anchor stablecoin for
- * on-chain PulseX pricing. One token's `getAmountsOut` ending in this address
- * yields that token's USD price directly (DAI is treated as exactly $1).
- *
- * Kept as an exported constant so the anchor can be swapped without touching the
- * pricing math. Mirrors `DAI_ADDRESS` in `packages/tx-report/src/server/prices.ts`.
- */
 export const PULSECHAIN_USD_ANCHOR_ADDRESS = '0xefd766ccb38eaf1dfd701853bfce31359239f305';
-/** Decimals of the {@link PULSECHAIN_USD_ANCHOR_ADDRESS} stablecoin. */
 export const PULSECHAIN_USD_ANCHOR_DECIMALS = 18;
-/** Wrapped PLS on PulseChain — the routing intermediary for PulseX paths. */
 export const WPLS_ADDRESS = nativeAssetOut[Chains.PLS];
-/** The native (gas) token sentinel address used across the dapp. */
 const NATIVE_TOKEN_ADDRESS = '0x0000000000000000000000000000000000000000';
-/** Lowercases an address for case-insensitive map keys and comparisons. */
 export const lowercaseAddress = (address) => address.toLowerCase();
-/** True when two addresses are equal ignoring case (and 0x-checksum casing). */
 const sameAddress = (left, right) => lowercaseAddress(left) === lowercaseAddress(right);
-/**
- * Map key for a foreign (LI.FI-priced) token: `${chainId}-${lowercased address}`.
- * Matches the key the UI builds when assembling the LI.FI price map.
- */
 export const lifiPriceKey = (chainId, address) => `${chainId}-${lowercaseAddress(address)}`;
-/** True when a chain id is priced on-chain via PulseX (mainnet or V4 testnet). */
 export const isPulsechain = (chainId) => chainId === PULSECHAIN_CHAIN_ID || chainId === PULSECHAIN_TESTNET_CHAIN_ID;
-/**
- * The PulseChain-origin address a bridged token backs out to, when the token's
- * `extensions.bridgeInfo` records a PulseChain counterpart. Bridged tokens are
- * 1:1 with their origin, so the origin's PulseX price is the token's USD value.
- *
- * @param token - the token whose PulseChain-origin link to resolve
- * @returns the PulseChain origin address, or null when the token has no such link
- */
 export const pulsechainOriginAddress = (token) => {
     const link = token.extensions?.bridgeInfo?.[PULSECHAIN_CHAIN_ID];
     if (!link) {
@@ -52,22 +17,6 @@ export const pulsechainOriginAddress = (token) => {
     }
     return link.tokenAddress;
 };
-/**
- * The set of PulseX swap paths to price one whole unit of `token` into the USD
- * anchor stablecoin. Edge cases collapse to shorter paths:
- *
- * - `token` is the stablecoin itself -> no swap needed (priced as exactly 1).
- * - `token` is WPLS (or the native zero-address) -> `[WPLS, stable]` only.
- * - otherwise -> both `[token, WPLS, stable]` and `[token, stable]`.
- *
- * Returned addresses are always concrete (the native sentinel is rewritten to
- * WPLS) so they can be fed straight into `getAmountsOut`.
- *
- * @param options.token - the token (only its address is read) to build paths for
- * @param options.wpls - the wrapped-native intermediary (defaults to {@link WPLS_ADDRESS})
- * @param options.stable - the USD anchor (defaults to {@link PULSECHAIN_USD_ANCHOR_ADDRESS})
- * @returns `{ paths }` — the candidate paths; empty when the token is the stablecoin
- */
 export const pulsexPricePaths = ({ token, wpls = WPLS_ADDRESS, stable = PULSECHAIN_USD_ANCHOR_ADDRESS, }) => {
     const address = sameAddress(token.address, NATIVE_TOKEN_ADDRESS) ? wpls : token.address;
     if (sameAddress(address, stable)) {
@@ -83,11 +32,6 @@ export const pulsexPricePaths = ({ token, wpls = WPLS_ADDRESS, stable = PULSECHA
         ],
     };
 };
-/**
- * The final output amount of one `getAmountsOut` result, or null when the call
- * failed (Hex) or returned an empty array. The last element of a `bigint[]`
- * `getAmountsOut` is the output-token amount.
- */
 const finalOutput = (result) => {
     if (typeof result === 'string') {
         return null;
@@ -97,16 +41,6 @@ const finalOutput = (result) => {
     }
     return result[result.length - 1];
 };
-/**
- * Reduces every `getAmountsOut` result (across all paths and all routers for one
- * token) to a single USD price by taking the MAX final output, then scaling out
- * of the stablecoin's decimals. Failed/empty results are dropped; when none
- * succeed the price is null (no liquidity).
- *
- * @param options.results - the `getAmountsOut` outcomes for the token's paths/routers
- * @param options.stableDecimals - decimals of the anchor (defaults to {@link PULSECHAIN_USD_ANCHOR_DECIMALS})
- * @returns the USD price as a number, or null when no path produced a value
- */
 export const computeUsdPriceFromAmountsOut = ({ results, stableDecimals = PULSECHAIN_USD_ANCHOR_DECIMALS, }) => {
     const outputs = results.flatMap((result) => {
         const output = finalOutput(result);
@@ -121,22 +55,6 @@ export const computeUsdPriceFromAmountsOut = ({ results, stableDecimals = PULSEC
     }
     return Number(formatUnits(maxOutput, stableDecimals));
 };
-/**
- * Resolves a token's USD price using pre-fetched price maps, following the
- * co-designed precedence:
- *
- * 1. PulseChain (mainnet or V4 testnet): the token's own PulseX price.
- * 2. Bridged PulseChain-origin token: the origin's PulseX price (1:1 value).
- * 3. Genuinely foreign token: the LI.FI inline price.
- *
- * The stablecoin anchor itself resolves to exactly 1. All address lookups are
- * case-insensitive (maps are keyed by lowercased address).
- *
- * @param token - the token to price
- * @param options.pulsexPrices - lowercased PulseChain address -> USD price
- * @param options.lifiPrices - `${chainId}-${lowercased address}` -> USD price
- * @returns the USD price as a number, or null when no source can price it
- */
 export const resolveTokenPriceUsd = (token, { pulsexPrices, lifiPrices, }) => {
     const wrappedNative = sameChainWrappedNative(token);
     if (wrappedNative !== null) {
@@ -144,15 +62,6 @@ export const resolveTokenPriceUsd = (token, { pulsexPrices, lifiPrices, }) => {
     }
     return resolveOwnPriceUsd(token, { pulsexPrices, lifiPrices });
 };
-/**
- * The chain's canonical wrapped native address when `token` is the native
- * coin (zero address) or that wrapper itself, and null for every other token.
- * Only the SAME chain's pair is returned: a bridged copy of a wrapper on
- * another chain is a different token and keeps its own price.
- *
- * @param token - the token to test
- * @returns the wrapped native address on the token's own chain, or null
- */
 export const sameChainWrappedNative = (token) => {
     const wrapped = nativeAssetOut[toChain(token.chainId)];
     if (wrapped === undefined) {
@@ -161,22 +70,6 @@ export const sameChainWrappedNative = (token) => {
     const isNativeCoin = sameAddress(token.address, NATIVE_TOKEN_ADDRESS);
     return isNativeCoin || sameAddress(token.address, wrapped) ? wrapped : null;
 };
-/**
- * One price for a native coin and its canonical wrapper. The contract wraps
- * and unwraps 1:1, so two prices would show a value loss on a wrap step that
- * loses nothing.
- *
- * Off PulseChain the native coin's market feed (LI.FI) wins. The wrapper's
- * own price there is the PulseX price of its bridged copy (it carries a
- * PulseChain origin link), which is a derivative market with its own
- * premium or discount. The coin's feed prices the underlying asset. When the
- * feed has no native price, the wrapper's feed price, then its own resolved
- * price, stand in.
- *
- * On PulseChain both are priced by PulseX through the WPLS path, so the
- * wrapper's entry is used and the coin's entry stands in when the wrapper was
- * not in the priced set.
- */
 const resolveNativeFamilyPriceUsd = (token, wrappedNative, maps) => {
     const wrapped = { ...token, address: wrappedNative };
     if (isPulsechain(token.chainId)) {
@@ -187,7 +80,6 @@ const resolveNativeFamilyPriceUsd = (token, wrappedNative, maps) => {
         maps.lifiPrices.get(lifiPriceKey(token.chainId, wrappedNative)) ??
         resolveOwnPriceUsd(wrapped, maps));
 };
-/** The token's price by its own address, with no native-wrapper pairing. */
 const resolveOwnPriceUsd = (token, { pulsexPrices, lifiPrices, }) => {
     if (isPulsechain(token.chainId)) {
         if (sameAddress(token.address, PULSECHAIN_USD_ANCHOR_ADDRESS)) {
@@ -200,11 +92,6 @@ const resolveOwnPriceUsd = (token, { pulsexPrices, lifiPrices, }) => {
         if (sameAddress(origin, PULSECHAIN_USD_ANCHOR_ADDRESS)) {
             return 1;
         }
-        // Prefer the bridged origin's on-chain PulseX price. Fall back to the token's
-        // OWN home-chain LI.FI inline price when PulseX cannot price it — a bridged
-        // major (e.g. wrapped ether / wrapped binance coin) whose PulseChain pool path
-        // returns nothing would otherwise resolve to null despite a well-known market
-        // price on its home chain.
         return (pulsexPrices.get(lowercaseAddress(origin)) ??
             lifiPrices.get(lifiPriceKey(token.chainId, token.address)) ??
             null);

package/dist/providers.js

@@ -7,11 +7,9 @@ const lifiDescriptor = {
     id: 'lifi',
     label: 'LI.FI',
     supportedSourceEcosystems: ['evm'],
-    // Its contract-calls endpoint exists to deliver and then call something.
     executesDestinationCalls: true,
     destinationCallOriginChainIds: [Number(Chains.ETH)],
     destinationCallCarriesNativeValue: false,
-    // Its quote names the Diamond as `estimate.approvalAddress`.
     originTokenSpend: 'allowance',
     preQuote: {
         method: 'GET',
@@ -27,15 +25,10 @@ const lifiDescriptor = {
 const relayDescriptor = {
     id: 'relay',
     label: 'Relay',
-    // Relay carries every origin family the registry models. Listed explicitly
-    // rather than derived from the registry so that registering a future
-    // ecosystem does not silently claim Relay support the integration lacks.
     supportedSourceEcosystems: ['evm', 'svm', 'bvm', 'tvm', 'tonvm', 'hypevm'],
-    // Its solver performs the `txs` attached to a quote on arrival.
     executesDestinationCalls: true,
     destinationCallOriginChainIds: 'any',
     destinationCallCarriesNativeValue: true,
-    // Its quote carries an approve step; the parser lifts its spender.
     originTokenSpend: 'allowance',
     preQuote: {
         method: 'POST',
@@ -51,21 +44,10 @@ const relayDescriptor = {
 const nearIntentsDescriptor = {
     id: 'near-intents',
     label: 'NEAR Intents',
-    // ETHEREUM ORIGINS, AND THE CHAINS A READER PAYS BY HAND. The service
-    // carries Solana, Bitcoin, Tron, The Open Network and more, but it returns a
-    // deposit ADDRESS and no transaction. For a wallet-connected origin the
-    // transfer that funds a route has to be composed on this side, and only the
-    // Ethereum one is composed today (`nearIntentsOriginDeposit`); claiming a
-    // family whose transfer nothing here can build would offer a route that
-    // dead-ends at the signing step. A pay-by-hand chain needs nothing composed:
-    // the address and the amount ARE the deposit (`DepositAddressDeposit`).
     supportedSourceEcosystems: ['evm', 'zcash'],
-    // The measured answer, and the reason this provider's routes take two
-    // signatures. See the head of `near-intents.ts`.
     executesDestinationCalls: false,
     destinationCallOriginChainIds: [],
     destinationCallCarriesNativeValue: false,
-    // The reader sends the token to a deposit address.
     originTokenSpend: 'transfer',
     preQuote: {
         method: 'POST',
@@ -78,38 +60,13 @@ const nearIntentsDescriptor = {
         parse: parseNearIntentsQuote,
     },
 };
-/**
- * Every integrated provider. LI.FI is first: the interface preserves this order
- * in its active lists, and LI.FI-first is the existing tie-break that prefers
- * the verified provider on an equal-cost quote. NEAR Intents is last, so it
- * wins a tie against neither — appropriate for the one provider whose route
- * costs the reader a second signature.
- */
 export const providerRegistry = [
     lifiDescriptor,
     relayDescriptor,
     nearIntentsDescriptor,
 ];
 const byId = new Map(providerRegistry.map((descriptor) => [descriptor.id, descriptor]));
-/**
- * Looks up a provider descriptor for ANY carrier id, answering null for an id
- * the registry does not hold. The route-search engine carries hops for
- * carriers that are not providers at all (a local wrap, a pool swap, a
- * host's own plug-in), so a caller holding an open carrier id must ask this,
- * never cast the id to {@link ProviderId} and call {@link providerById}, which
- * throws for such an id.
- *
- * @param id - any carrier id
- * @returns the descriptor, or null when no provider is registered under `id`
- */
 export const findProviderById = (id) => byId.get(id) ?? null;
-/**
- * Looks up a provider descriptor. Total over the `ProviderId` union; throws only
- * if the registry is left incomplete.
- *
- * @param id - the provider key
- * @returns the descriptor whose `id` equals `id`
- */
 export const providerById = (id) => {
     const descriptor = byId.get(id);
     if (descriptor === undefined) {
@@ -117,47 +74,7 @@ export const providerById = (id) => {
     }
     return descriptor;
 };
-/**
- * The providers that can originate a route from `ecosystem`, in registry order.
- * This is the data that used to be the hand-written capability conditional.
- *
- * @param ecosystem - the source ecosystem
- * @returns the descriptors whose `supportedSourceEcosystems` include `ecosystem`
- */
 export const providersForOrigin = (ecosystem) => providerRegistry.filter((descriptor) => descriptor.supportedSourceEcosystems.includes(ecosystem));
-/**
- * The providers that may bid in the entry-anchor pre-quote for an origin.
- *
- * A STRICTER LIST THAN {@link providersForOrigin}, AND THE DIFFERENCE IS NOT
- * COSMETIC. The pre-quote exists for one purpose: to learn, for the reader's
- * fixed input, how much anchor an entry really delivers, so that figure can
- * become the exact-output target of the execution quote. The winner is whoever
- * delivers MOST.
- *
- * A provider that cannot execute the entry call can still win that comparison —
- * it has one less thing to pay for. Its number then becomes a target handed to
- * the providers that must actually fill it, and they cannot, so the whole entry
- * produces no route. The failure is silent and looks like an absent quote.
- *
- * So the pre-quote is restricted to providers that execute. This is not a
- * judgement about quality; it is that a pre-quote and an execution quote have
- * to be answerable by the same provider for the handoff between them to mean
- * anything.
- *
- * @param ecosystem - the source ecosystem
- * @returns the descriptors that may pre-quote this origin, in registry order
- */
 export const preQuoteProvidersForOrigin = (ecosystem) => providersForOrigin(ecosystem).filter((descriptor) => descriptor.executesDestinationCalls);
-// A request with no origin family is the existing-caller shape and is treated as
-// Ethereum, preserving the original single-ecosystem default.
 const ecosystemOf = (request) => request.originVmType ?? 'evm';
-/**
- * Whether a provider can quote a request's origin ecosystem, derived from the
- * registry. Equivalent to `providersForOrigin(...).some(...)`, kept as a named
- * predicate for the call sites that ask about one provider at a time.
- *
- * @param provider - the aggregator under consideration
- * @param request - the request whose origin is being checked
- * @returns true when the provider supports the request's origin ecosystem
- */
 export const providerSupportsOrigin = (provider, request) => providerById(provider).supportedSourceEcosystems.includes(ecosystemOf(request));

package/dist/quote-fees.js

@@ -1,37 +1,5 @@
-/**
- * What a consolidated route actually charges, normalized across the aggregators.
- *
- * WHY THIS EXISTS. A quote used to carry `fromAmount` and nothing else about
- * cost, so the interface could show the reader only the omnibridge crossing fee
- * — a figure that is real, and on a twenty-five dollar transfer is a rounding
- * error beside what the aggregator takes. Measured on one live route on
- * 2026-09-01: Relay charged 1.466338 USD Coin, or 5.54%, and none of it
- * appeared anywhere on screen.
- *
- * THE FLAG THAT MATTERS IS `includedInFromAmount`. The two providers express
- * cost differently, and the difference is not cosmetic:
- *
- *   Relay folds everything into `fromAmount`. You send 26.466338 to receive
- *   25.000000, and the 1.466338 difference IS the fee.
- *
- *   LI.FI does not. On the same route it quoted `fromAmount` 25.317074 and a
- *   SEPARATE LayerZero fee of 0.000561734871157119 ether — about 1.37 dollars —
- *   marked `included: false`, which the sender pays on top in native currency.
- *
- * So comparing the two on `fromAmount` alone reads LI.FI as more than a dollar
- * cheaper when it is in fact slightly dearer. Anything that ranks or displays
- * cost has to add the charges that sit outside `fromAmount`, and that is what
- * this flag is for.
- */
 const asRecord = (value) => typeof value === 'object' && value !== null ? value : null;
 const asNumber = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
-/**
- * Reads a provider's currency block into a token descriptor.
- *
- * Returns null rather than filling in defaults: a charge whose token is unknown
- * cannot be formatted, and inventing eighteen decimals for it would print a
- * number wrong by many orders of magnitude.
- */
 const feeToken = (value) => {
     const currency = asRecord(value);
     const decimals = asNumber(currency?.decimals);
@@ -41,15 +9,11 @@ const feeToken = (value) => {
     }
     return { symbol: currency.symbol, decimals, chainId };
 };
-/** Parses a provider's amount string, dropping a charge that is zero or unreadable. */
 const feeAmount = (value) => {
     if (typeof value !== 'string' && typeof value !== 'number') {
         return null;
     }
     try {
-        // Relay reports "0.0" for an unused fee slot, which BigInt rejects; a
-        // fractional string here is always zero in practice, and a charge we cannot
-        // read exactly is one we must not display.
         const amount = BigInt(String(value).split('.')[0] ?? '');
         return amount > 0n ? amount : null;
     }
@@ -58,19 +22,6 @@ const feeAmount = (value) => {
     }
 };
 const usdOf = (value) => typeof value === 'string' || typeof value === 'number' ? String(value) : null;
-/**
- * The charges Relay reports, in the order a reader meets them.
- *
- * `fees.relayer` IS DELIBERATELY SKIPPED. It is the sum of `relayerGas` and
- * `relayerService`, so listing it beside them would count the same money twice
- * and make the breakdown disagree with the amount the sender pays.
- *
- * `fees.gas` is the sender's OWN origin-chain transaction cost. It sits outside
- * `fromAmount` because the wallet pays it directly, which is exactly the case
- * `includedInFromAmount` exists to mark.
- * @param payload - the raw body from Relay's quote endpoint
- * @returns the charges, in display order
- */
 export const relayQuoteFees = (payload) => {
     const fees = asRecord(asRecord(payload)?.fees);
     if (!fees) {
@@ -101,16 +52,6 @@ export const relayQuoteFees = (payload) => {
         ];
     });
 };
-/**
- * The charges LI.FI reports.
- *
- * `feeCosts` CARRIES ITS OWN `included` FLAG and it is the whole point of
- * reading this: a fee marked `included: false` is paid on top of `fromAmount`,
- * in that fee's own token, and on a live route it was worth more than a dollar.
- * `gasCosts` is the sender's own origin transaction and is never included.
- * @param payload - the raw body from LI.FI's quote endpoint
- * @returns the charges, in display order
- */
 export const lifiQuoteFees = (payload) => {
     const estimate = asRecord(asRecord(payload)?.estimate);
     if (!estimate) {
@@ -132,9 +73,6 @@ export const lifiQuoteFees = (payload) => {
                 amount,
                 token,
                 amountUsd: usdOf(fee?.amountUSD),
-                // Absent is treated as NOT included. A fee we wrongly call included
-                // disappears from the total and understates the route; one we wrongly
-                // call excluded overstates it. Overstating is the safe direction.
                 includedInFromAmount: fee?.included === true,
             },
         ];
@@ -159,21 +97,6 @@ export const lifiQuoteFees = (payload) => {
     });
     return [...fromFeeCosts, ...fromGasCosts];
 };
-/**
- * What the route costs the sender all in, in United States dollars.
- *
- * `fromAmount` already contains every charge marked included, so only the ones
- * marked otherwise are added. This is the figure two providers must be compared
- * on: ranking them on `fromAmount` alone picked LI.FI over Relay by more than a
- * dollar on a route where LI.FI was in fact the dearer of the two, because its
- * LayerZero fee is charged outside the amount.
- *
- * Returns null when the input's own dollar value is unknown — a partial total
- * would rank routes against each other on different bases.
- * @param quote.fromAmountUsd - the provider's dollar value for the input amount
- * @param quote.fees - the route's charges
- * @returns the all-in dollar cost, or null when it cannot be totalled
- */
 export const totalQuoteCostUsd = ({ fromAmountUsd, fees, }) => {
     if (fromAmountUsd === null) {
         return null;
@@ -187,9 +110,6 @@ export const totalQuoteCostUsd = ({ fromAmountUsd, fees, }) => {
             return total;
         }
         const value = Number(fee.amountUsd);
-        // A charge outside the amount whose dollar value we cannot read is left out
-        // rather than guessed. It is named in the breakdown either way, so the
-        // reader still sees it even when the total cannot count it.
         return Number.isFinite(value) ? total + value : total;
     }, base);
 };