@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/providers.js

@@ -0,0 +1,157 @@
+import { buildLifiContractCallsRequest, parseLifiContractCallsQuote, } from './consolidated-quote.js';
+import { Chains } from './config.js';
+import { buildLifiPreQuoteRequest, buildRelayPreQuoteRequest, parseLifiPreQuote, parseRelayPreQuote, } from './pre-quote.js';
+import { buildNearIntentsPreQuoteRequest, buildNearIntentsQuoteRequest, parseNearIntentsPreQuote, parseNearIntentsQuote, } from './near-intents.js';
+import { buildRelayQuoteRequest, parseRelayQuote } from './relay-quote.js';
+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,
+    preQuote: {
+        method: 'GET',
+        build: buildLifiPreQuoteRequest,
+        parse: parseLifiPreQuote,
+    },
+    executionQuote: {
+        method: 'POST',
+        build: buildLifiContractCallsRequest,
+        parse: parseLifiContractCallsQuote,
+    },
+};
+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,
+    preQuote: {
+        method: 'POST',
+        build: buildRelayPreQuoteRequest,
+        parse: parseRelayPreQuote,
+    },
+    executionQuote: {
+        method: 'POST',
+        build: buildRelayQuoteRequest,
+        parse: parseRelayQuote,
+    },
+};
+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,
+    preQuote: {
+        method: 'POST',
+        build: buildNearIntentsPreQuoteRequest,
+        parse: parseNearIntentsPreQuote,
+    },
+    executionQuote: {
+        method: 'POST',
+        build: buildNearIntentsQuoteRequest,
+        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) {
+        throw new Error(`no provider descriptor registered for id "${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.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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.
+ */
+/** The token a charge is denominated in, enough to format it. */
+export type QuoteFeeToken = {
+    symbol: string;
+    decimals: number;
+    chainId: number;
+};
+/**
+ * What a charge IS, independent of the name its provider gives it.
+ *
+ * Deliberately coarse. The provider's own wording travels in `label`, so this
+ * only has to carry the distinction a reader acts on: is this the network's
+ * cost, somebody's margin, or our own referral.
+ */
+export type QuoteFeeKind = 'gas' | 'service' | 'integrator';
+/** One charge on a route. */
+export type QuoteFee = {
+    kind: QuoteFeeKind;
+    /** The provider's own name for it, so a reader can reconcile against them. */
+    label: string;
+    /** The charge, in the token's base units. */
+    amount: bigint;
+    token: QuoteFeeToken;
+    /** United States dollar value, exactly as the provider reported it. */
+    amountUsd: string | null;
+    /**
+     * FALSE means the sender pays this ON TOP of `fromAmount`.
+     *
+     * Getting this backwards double-counts a fee or hides one entirely, and in
+     * both directions the number on screen is wrong in the direction that
+     * flatters the route.
+     */
+    includedInFromAmount: boolean;
+};
+/**
+ * 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 declare const relayQuoteFees: (payload: unknown) => QuoteFee[];
+/**
+ * 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 declare const lifiQuoteFees: (payload: unknown) => QuoteFee[];
+/**
+ * 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 declare const totalQuoteCostUsd: ({ fromAmountUsd, fees, }: {
+    fromAmountUsd: string | null;
+    fees: QuoteFee[];
+}) => number | null;

package/dist/quote-fees.js

@@ -0,0 +1,195 @@
+/**
+ * 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);
+    const chainId = asNumber(currency?.chainId);
+    if (typeof currency?.symbol !== 'string' || decimals === null || chainId === null) {
+        return null;
+    }
+    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;
+    }
+    catch {
+        return null;
+    }
+};
+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) {
+        return [];
+    }
+    const rows = [
+        { key: 'relayerGas', label: 'Destination network cost', kind: 'gas', included: true },
+        { key: 'relayerService', label: 'Relay service fee', kind: 'service', included: true },
+        { key: 'app', label: 'Referral fee', kind: 'integrator', included: true },
+        { key: 'gas', label: 'Origin network cost', kind: 'gas', included: false },
+    ];
+    return rows.flatMap(({ key, label, kind, included }) => {
+        const node = asRecord(fees[key]);
+        const amount = feeAmount(node?.amount);
+        const token = feeToken(node?.currency);
+        if (amount === null || token === null) {
+            return [];
+        }
+        return [
+            {
+                kind,
+                label,
+                amount,
+                token,
+                amountUsd: usdOf(node?.amountUsd),
+                includedInFromAmount: included,
+            },
+        ];
+    });
+};
+/**
+ * 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) {
+        return [];
+    }
+    const feeCosts = Array.isArray(estimate.feeCosts) ? estimate.feeCosts : [];
+    const gasCosts = Array.isArray(estimate.gasCosts) ? estimate.gasCosts : [];
+    const fromFeeCosts = feeCosts.flatMap((entry) => {
+        const fee = asRecord(entry);
+        const amount = feeAmount(fee?.amount);
+        const token = feeToken(fee?.token);
+        if (amount === null || token === null) {
+            return [];
+        }
+        return [
+            {
+                kind: 'service',
+                label: typeof fee?.name === 'string' ? fee.name : 'Provider fee',
+                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,
+            },
+        ];
+    });
+    const fromGasCosts = gasCosts.flatMap((entry) => {
+        const gas = asRecord(entry);
+        const amount = feeAmount(gas?.amount);
+        const token = feeToken(gas?.token);
+        if (amount === null || token === null) {
+            return [];
+        }
+        return [
+            {
+                kind: 'gas',
+                label: 'Origin network cost',
+                amount,
+                token,
+                amountUsd: usdOf(gas?.amountUSD),
+                includedInFromAmount: false,
+            },
+        ];
+    });
+    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;
+    }
+    const base = Number(fromAmountUsd);
+    if (!Number.isFinite(base)) {
+        return null;
+    }
+    return fees.reduce((total, fee) => {
+        if (fee.includedInFromAmount) {
+            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);
+};

package/dist/referral.d.ts

@@ -0,0 +1,77 @@
+import type { Hex } from 'viem';
+/**
+ * Referral configuration — the one place to set who gets paid.
+ *
+ * This module exists so the payout address is a single named edit rather than a
+ * constant buried among API urls. It deliberately imports nothing but a type, so
+ * the interface can read the address without pulling in a quote builder.
+ */
+/**
+ * Gibs Finance's own integrator identifier with LI.FI and Relay. LI.FI pays its
+ * integrator share against this string — the payout account is configured on
+ * LI.FI's side, which is why LI.FI needs no address here and Relay does.
+ *
+ * This is Gibs Finance's identity, not a setting for other consumers. The
+ * Relay API key that used to live beside it moved into the Gibs interface's
+ * own configuration (`packages/ui/src/lib/config.ts`): this package ships no
+ * key. Pass your own identifiers on each request — see the README.
+ */
+export declare const referralIntegrator = "gibs.finance";
+/**
+ * Resolves one attribution field (a LI.FI `integrator`, a Relay `referrer`)
+ * from a caller's override and this package's default for it.
+ *
+ * Three states, not two:
+ * - `undefined` (left out): the package default — which may itself be
+ *   `undefined`, meaning the field is not sent.
+ * - `null`: the field is OMITTED from the request. Never sent as `''`: Relay
+ *   reads any `referrer`, an empty one included, as "a referrer was supplied".
+ * - a string: sent as-is.
+ *
+ * @param override - the caller's value for the field
+ * @param packageDefault - the value used when the caller leaves the field out
+ * @returns the value to send, or undefined to omit the field
+ */
+export declare const resolveAttribution: (override: string | null | undefined, packageDefault: string | undefined) => string | undefined;
+/**
+ * Payout address for Relay application fees.
+ *
+ * Set to the owner's receiving wallet. Setting it back to `null` is a working
+ * state rather than a broken one, and is the way to stop collecting: Relay
+ * rejects a fee entry that names no recipient, so the fee is omitted from the
+ * request entirely and nothing is charged. Every consumer already reads it this
+ * way — see {@link referralIsCollectable}.
+ *
+ * The literal is stored CHECKSUMMED (mixed case). That is not decoration: the
+ * mixed case IS the checksum, so a typo in the address fails `getAddress`
+ * instead of silently paying a wrong-but-valid account. Verified against viem's
+ * `getAddress` before being written here.
+ *
+ * One address serves every chain: Relay pays application fees on the DESTINATION
+ * chain, and every destination this app bridges to is Ethereum-style, so an
+ * ordinary Ethereum address receives from all of them.
+ */
+export declare const relayReferralRecipient: Hex | null;
+/**
+ * Default application fee in basis points. Ten basis points is one tenth of one
+ * percent. The interface can override it per provider in stored settings; this
+ * is the value a reader who has never touched the setting gets.
+ */
+export declare const defaultReferralFeeBasisPoints = 10n;
+/**
+ * Whether a referral fee will ACTUALLY be collected, as opposed to merely being
+ * switched on.
+ *
+ * The distinction is the point of this helper. Relay's fee needs three things to
+ * be true at once, and the interface used to show a percentage whenever the
+ * first was true — so the fee row read "0.10%" while the missing recipient meant
+ * nothing was charged at all. Ask this rather than reading `enabled` alone.
+ *
+ * @param options - the switch state, the fee size, and the payout address
+ * @returns true only when a fee will reach a recipient
+ */
+export declare const referralIsCollectable: ({ enabled, basisPoints, recipient, }: {
+    enabled: boolean;
+    basisPoints: bigint;
+    recipient: Hex | null;
+}) => boolean;

package/dist/referral.js

@@ -0,0 +1,72 @@
+/**
+ * Referral configuration — the one place to set who gets paid.
+ *
+ * This module exists so the payout address is a single named edit rather than a
+ * constant buried among API urls. It deliberately imports nothing but a type, so
+ * the interface can read the address without pulling in a quote builder.
+ */
+/**
+ * Gibs Finance's own integrator identifier with LI.FI and Relay. LI.FI pays its
+ * integrator share against this string — the payout account is configured on
+ * LI.FI's side, which is why LI.FI needs no address here and Relay does.
+ *
+ * This is Gibs Finance's identity, not a setting for other consumers. The
+ * Relay API key that used to live beside it moved into the Gibs interface's
+ * own configuration (`packages/ui/src/lib/config.ts`): this package ships no
+ * key. Pass your own identifiers on each request — see the README.
+ */
+export const referralIntegrator = 'gibs.finance';
+/**
+ * Resolves one attribution field (a LI.FI `integrator`, a Relay `referrer`)
+ * from a caller's override and this package's default for it.
+ *
+ * Three states, not two:
+ * - `undefined` (left out): the package default — which may itself be
+ *   `undefined`, meaning the field is not sent.
+ * - `null`: the field is OMITTED from the request. Never sent as `''`: Relay
+ *   reads any `referrer`, an empty one included, as "a referrer was supplied".
+ * - a string: sent as-is.
+ *
+ * @param override - the caller's value for the field
+ * @param packageDefault - the value used when the caller leaves the field out
+ * @returns the value to send, or undefined to omit the field
+ */
+export const resolveAttribution = (override, packageDefault) => (override === null ? undefined : (override ?? packageDefault));
+/**
+ * Payout address for Relay application fees.
+ *
+ * Set to the owner's receiving wallet. Setting it back to `null` is a working
+ * state rather than a broken one, and is the way to stop collecting: Relay
+ * rejects a fee entry that names no recipient, so the fee is omitted from the
+ * request entirely and nothing is charged. Every consumer already reads it this
+ * way — see {@link referralIsCollectable}.
+ *
+ * The literal is stored CHECKSUMMED (mixed case). That is not decoration: the
+ * mixed case IS the checksum, so a typo in the address fails `getAddress`
+ * instead of silently paying a wrong-but-valid account. Verified against viem's
+ * `getAddress` before being written here.
+ *
+ * One address serves every chain: Relay pays application fees on the DESTINATION
+ * chain, and every destination this app bridges to is Ethereum-style, so an
+ * ordinary Ethereum address receives from all of them.
+ */
+export const relayReferralRecipient = '0xAF2ce0189f46f5663715b0b9ED2a10eA924AB9B0';
+/**
+ * Default application fee in basis points. Ten basis points is one tenth of one
+ * percent. The interface can override it per provider in stored settings; this
+ * is the value a reader who has never touched the setting gets.
+ */
+export const defaultReferralFeeBasisPoints = 10n;
+/**
+ * Whether a referral fee will ACTUALLY be collected, as opposed to merely being
+ * switched on.
+ *
+ * The distinction is the point of this helper. Relay's fee needs three things to
+ * be true at once, and the interface used to show a percentage whenever the
+ * first was true — so the fee row read "0.10%" while the missing recipient meant
+ * nothing was charged at all. Ask this rather than reading `enabled` alone.
+ *
+ * @param options - the switch state, the fee size, and the payout address
+ * @returns true only when a fee will reach a recipient
+ */
+export const referralIsCollectable = ({ enabled, basisPoints, recipient, }) => enabled && basisPoints > 0n && recipient !== null;

package/dist/relay-currencies.d.ts

@@ -0,0 +1,47 @@
+import type { Token } from './types.js';
+/**
+ * Relay currencies endpoint. Anonymous access works at the same 50-requests-per-
+ * minute tier as the quote endpoint; used to discover the source tokens a
+ * non-Ethereum origin chain (Solana, Bitcoin) can bridge from.
+ */
+export declare const relayCurrenciesUrl = "https://api.relay.link/currencies/v2";
+/** The JSON body for `POST /currencies/v2`. */
+export type RelayCurrenciesRequestBody = {
+    /** Relay chain identifiers to list currencies for. */
+    chainIds: number[];
+    /** Optional cap on how many currencies Relay returns per chain. */
+    limit?: number;
+};
+/**
+ * Builds the Relay currencies request body.
+ *
+ * @returns the request body, or null when no chain ids are supplied
+ */
+export declare const buildRelayCurrenciesRequest: ({ chainIds, limit, }: {
+    chainIds: number[];
+    limit?: number;
+}) => RelayCurrenciesRequestBody | null;
+/**
+ * Relay's own chain registry — the provider's word on which chains it
+ * supports AT ALL, distinct from `/currencies/v2` (which chains currently
+ * have priced currencies). A chain absent here can never be asked about, on
+ * `/currencies/v2` or `/quote` alike; see `parseRelayChains`.
+ */
+export declare const relayChainsUrl = "https://api.relay.link/chains";
+/**
+ * Normalizes a `GET /chains` response body to the chain ids Relay lists.
+ * Mirrors `parseLifiChains` (`consolidated-quote.ts`) for LI.FI's own chain
+ * list: read the provider's own registry, never a hand-written exclusion.
+ *
+ * @returns the chain ids Relay lists, or null when the payload shape is unexpected
+ */
+export declare const parseRelayChains: (payload: unknown) => number[] | null;
+/**
+ * Maps Relay's flat `/currencies/v2` array onto the shared `Token` shape. A
+ * Relay currency's `address` is already a string (a Solana mint or a Bitcoin
+ * native address), so no widening is needed. Malformed entries are skipped
+ * rather than failing the whole list.
+ *
+ * @returns the tokens, or an empty list when the payload is not an array
+ */
+export declare const parseRelayCurrencies: (payload: unknown) => Token[];