@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/route-steps.d.ts

@@ -0,0 +1,138 @@
+import type { Hex } from 'viem';
+/**
+ * The semantic kind of a single route step. These map to the provider's
+ * action type as faithfully as the response data allows.
+ *
+ * - `bridge`  — cross-chain transfer (different `fromChainId` and `toChainId`)
+ * - `swap`    — same-chain token exchange via a decentralized exchange
+ * - `wrap`    — native asset → wrapped native (e.g. ETH → WETH)
+ * - `unwrap`  — wrapped native → native asset
+ * - `send`    — plain transfer with no token conversion
+ */
+export type RouteStepKind = 'bridge' | 'swap' | 'wrap' | 'unwrap' | 'send';
+/**
+ * A normalized, provider-agnostic description of one leg in a bridge route.
+ * The UI renders these in order to show the user what will happen to their
+ * funds at each stage of the journey.
+ */
+export type RouteStep = {
+    /** Semantic category of this step. */
+    kind: RouteStepKind;
+    /**
+     * Human-readable, fully-spelled-out label for this step (no acronyms).
+     * Example: "Bridge to Ethereum" or "Swap on Uniswap V3".
+     */
+    label: string;
+    /** Chain the step starts on, as a decimal chain id. */
+    fromChainId: number;
+    /** Chain the step lands on, as a decimal chain id. */
+    toChainId: number;
+    /**
+     * Token address the step consumes.
+     *
+     * Typed as `string` rather than `Hex` because a leg can start on a
+     * non-Ethereum chain, where the token identifier is not `0x`-prefixed — a
+     * Bitcoin address, a Solana or Tron base58 address, a The Open Network
+     * user-friendly address. Treat it as an opaque identifier for display and
+     * prefer {@link fromTokenSymbol} when showing it.
+     */
+    fromToken: string;
+    /** Token address the step produces. `string` for the same reason as {@link fromToken}. */
+    toToken: string;
+    /**
+     * Ticker symbol of the consumed token (e.g. "USDC"), when the provider
+     * supplies it. Null when the response omitted the token's symbol — callers
+     * showing a conversion should fall back to a shortened address rather than the
+     * full address, which is unreadable.
+     */
+    fromTokenSymbol: string | null;
+    /** Ticker symbol of the produced token, or null when the provider omits it. */
+    toTokenSymbol: string | null;
+    /**
+     * Logo image url for the CONSUMED token, when the provider supplies one. This is
+     * the token's own image, not the service provider's ({@link providerLogoUri}).
+     * Carried because a step can start on a non-Ethereum chain, where the image
+     * service has no entry keyed by a checksummed hex address and the provider's url
+     * is the only image available. Null when the provider omitted it.
+     */
+    fromTokenLogoUri: string | null;
+    /** Logo image url for the PRODUCED token. Null for the same reasons as {@link fromTokenLogoUri}. */
+    toTokenLogoUri: string | null;
+    /**
+     * The router or contract this step calls, when the provider supplies it.
+     * Null when the provider does not expose a contract address for this leg.
+     */
+    router: Hex | null;
+    /**
+     * Logo image url for the service provider that performs this step (for a
+     * LI.FI route this is the per-step tool: the decentralized exchange or bridge
+     * the aggregator routes through, for example Uniswap or Stargate). Taken from
+     * the provider's per-step tool details when present. Null when the provider
+     * supplied no logo url for the step, in which case the consuming interface
+     * falls back to a provider-initials tile rather than a broken image.
+     */
+    providerLogoUri: string | null;
+    /**
+     * Estimated output of this step in base units, when the provider supplies it.
+     * Null when the provider does not report an estimated output for this leg.
+     */
+    estimatedOut: bigint | null;
+    /**
+     * Estimated United States dollar cost of THIS step — the sum of the provider's
+     * per-step protocol fees (`feeCosts`) and gas costs (`gasCosts`) — so the UI can
+     * show a fee on every hop rather than only a single route total. Null when the
+     * provider reported no per-step costs (the UI then shows no fee for the hop).
+     */
+    feeUsd: number | null;
+    /**
+     * Estimated United States dollar GAS cost of THIS step — the provider's
+     * `gasCosts` ALONE, with the protocol-fee portion ({@link feeUsd}'s `feeCosts`
+     * component) excluded. Surfaced separately from {@link feeUsd} because the two
+     * costs enter route comparison differently: protocol fees and slippage are
+     * already embedded in the quote's `fromAmount` (the backward-quoted origin
+     * token), whereas gas is paid ON TOP in the network's native token. Route
+     * ranking therefore charges only this gas figure on top of the paid-versus-
+     * delivered spread, so it must not double-count the protocol fees. Null when the
+     * provider reported no gas costs for the leg.
+     */
+    gasUsd: number | null;
+};
+/**
+ * Normalizes a LI.FI `includedSteps` array into the provider-agnostic
+ * `RouteStep[]` shape. Steps with missing or non-hex token addresses are
+ * silently dropped rather than causing the whole normalization to fail.
+ *
+ * @param steps - the raw `includedSteps` value from a LI.FI quote response,
+ *   or `undefined` when the field was absent (trimmed responses)
+ * @returns ordered list of normalized steps; empty when no usable legs are present
+ */
+export declare const normalizeLifiSteps: (steps: unknown) => RouteStep[];
+/**
+ * Normalizes a Relay quote into the provider-agnostic `RouteStep[]` shape.
+ *
+ * Relay's `steps` array holds only OPERATIONAL steps (`approve` and `deposit`) —
+ * what the user signs, not where the funds go. The route itself lives in
+ * `details.route`, which describes the journey as an origin leg and a
+ * destination leg, each with an input and an output currency. Reading those four
+ * endpoints in order and emitting a step between each consecutive pair recovers
+ * the real path, so a Bitcoin origin renders as "Bitcoin → United States Dollar
+ * Coin on Ethereum" rather than as nothing at all.
+ *
+ * Consecutive endpoints that name the same currency on the same chain are
+ * collapsed, because Relay repeats an endpoint when a leg performs no
+ * conversion. A step's kind follows from its chains: crossing chains is a
+ * `bridge`, staying put is a `swap`. Relay reports no wrap/unwrap distinction,
+ * so none is invented.
+ *
+ * Costs are route-level in Relay's response, not per leg, so they are attached
+ * to the FIRST step — the one the user actually signs and pays at. `gasUsd`
+ * carries `fees.gas` alone (the origin transaction's gas, paid on top in the
+ * network's native token), while `feeUsd` adds the relayer and application fees
+ * on top of it, matching how the LI.FI normalizer splits the two. The relayer
+ * fee's `relayerGas`/`relayerService` components are deliberately NOT summed:
+ * they add up to `relayer` exactly, so counting them would double the fee.
+ *
+ * @param quote - a raw Relay quote response body
+ * @returns ordered list of normalized steps; empty when no route is present
+ */
+export declare const normalizeRelaySteps: (quote: unknown) => RouteStep[];

package/dist/route-steps.js

@@ -0,0 +1,305 @@
+import { chainDisplayName } from './chain-names.js';
+const isHexString = (value) => typeof value === 'string' && value.startsWith('0x');
+/**
+ * Sums the `amountUSD` field across a LI.FI cost array (`feeCosts` or
+ * `gasCosts`), tolerating missing/malformed entries by skipping them. LI.FI
+ * reports each cost's dollar value as a numeric string; entries without a finite
+ * `amountUSD` contribute nothing rather than poisoning the sum with `NaN`.
+ *
+ * @param costs - a raw `feeCosts`/`gasCosts` value from a step estimate
+ * @returns the total United States dollar cost; zero when none are present
+ */
+const sumUsdCosts = (costs) => {
+    if (!Array.isArray(costs)) {
+        return 0;
+    }
+    return costs.reduce((total, raw) => {
+        const cost = asRecord(raw);
+        const amountUsd = typeof cost?.amountUSD === 'string' ? Number(cost.amountUSD) : Number.NaN;
+        return Number.isFinite(amountUsd) ? total + amountUsd : total;
+    }, 0);
+};
+const asRecord = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return null;
+    }
+    return value;
+};
+/**
+ * Maps a LI.FI step type string to the normalized `RouteStepKind`.
+ *
+ * LI.FI reports `"cross"` for bridge legs and `"swap"` for same-chain
+ * exchanges. `"wrap"` and `"unwrap"` map directly. Unknown types fall back to
+ * `"send"` rather than failing the whole normalization.
+ */
+const lifiTypeToKind = (type) => {
+    if (type === 'cross')
+        return 'bridge';
+    if (type === 'swap')
+        return 'swap';
+    if (type === 'wrap')
+        return 'wrap';
+    if (type === 'unwrap')
+        return 'unwrap';
+    return 'send';
+};
+/**
+ * Builds a human-readable label for a LI.FI step.
+ *
+ * Labels are fully spelled out (no acronyms) so they can be displayed
+ * directly in the UI without any post-processing.
+ */
+const buildLifiLabel = (kind, toChainId, toolName) => {
+    if (kind === 'bridge')
+        return `Bridge to ${chainDisplayName(toChainId)}`;
+    if (kind === 'swap')
+        return `Swap on ${toolName}`;
+    if (kind === 'wrap')
+        return `Wrap to native token on ${chainDisplayName(toChainId)}`;
+    if (kind === 'unwrap')
+        return `Unwrap to native on ${chainDisplayName(toChainId)}`;
+    return `Transfer on ${chainDisplayName(toChainId)}`;
+};
+/**
+ * Normalizes a LI.FI `includedSteps` array into the provider-agnostic
+ * `RouteStep[]` shape. Steps with missing or non-hex token addresses are
+ * silently dropped rather than causing the whole normalization to fail.
+ *
+ * @param steps - the raw `includedSteps` value from a LI.FI quote response,
+ *   or `undefined` when the field was absent (trimmed responses)
+ * @returns ordered list of normalized steps; empty when no usable legs are present
+ */
+export const normalizeLifiSteps = (steps) => {
+    if (!Array.isArray(steps) || steps.length === 0) {
+        return [];
+    }
+    const result = [];
+    for (const raw of steps) {
+        const step = asRecord(raw);
+        if (!step) {
+            continue;
+        }
+        const type = typeof step.type === 'string' ? step.type : 'send';
+        const action = asRecord(step.action);
+        if (!action) {
+            continue;
+        }
+        const fromChainId = typeof action.fromChainId === 'number' ? action.fromChainId : null;
+        const toChainId = typeof action.toChainId === 'number' ? action.toChainId : null;
+        if (fromChainId === null || toChainId === null) {
+            continue;
+        }
+        // A step that changes chains IS a bridge, whatever the provider called its
+        // type. LI.FI labels most cross-chain legs `"cross"`, but some (e.g. an Across
+        // leg, or a `"protocol"`/`"lifi"`-typed leg) would otherwise fall through to
+        // the generic `"send"` kind and read as "Transfer on Ethereum" — misleading,
+        // since the funds are actually being BRIDGED there. Deciding from the chains
+        // rather than the type string keeps the label honest.
+        const typeKind = lifiTypeToKind(type);
+        const kind = typeKind === 'send' && fromChainId !== toChainId ? 'bridge' : typeKind;
+        const fromTokenRecord = asRecord(action.fromToken);
+        const toTokenRecord = asRecord(action.toToken);
+        const fromToken = isHexString(fromTokenRecord?.address) ? fromTokenRecord.address : null;
+        const toToken = isHexString(toTokenRecord?.address) ? toTokenRecord.address : null;
+        if (!fromToken || !toToken) {
+            continue;
+        }
+        const fromTokenSymbol = typeof fromTokenRecord?.symbol === 'string' ? fromTokenRecord.symbol : null;
+        const toTokenSymbol = typeof toTokenRecord?.symbol === 'string' ? toTokenRecord.symbol : null;
+        const fromTokenLogoUri = typeof fromTokenRecord?.logoURI === 'string' ? fromTokenRecord.logoURI : null;
+        const toTokenLogoUri = typeof toTokenRecord?.logoURI === 'string' ? toTokenRecord.logoURI : null;
+        const toolDetails = asRecord(step.toolDetails);
+        const toolName = typeof toolDetails?.name === 'string'
+            ? toolDetails.name
+            : typeof step.tool === 'string'
+                ? step.tool
+                : 'unknown';
+        // The per-step tool's logo, when the provider supplies one. This is the best
+        // source for a real service-provider image on the consuming interface (for
+        // example the Uniswap or Stargate logo for the leg the aggregator routes
+        // through). Null when absent, so the interface falls back to an initials tile.
+        const providerLogoUri = typeof toolDetails?.logoURI === 'string' ? toolDetails.logoURI : null;
+        const label = buildLifiLabel(kind, toChainId, toolName);
+        const estimate = asRecord(step.estimate);
+        const estimatedOut = typeof estimate?.toAmount === 'string' && estimate.toAmount !== ''
+            ? (() => {
+                try {
+                    return BigInt(estimate.toAmount);
+                }
+                catch {
+                    return null;
+                }
+            })()
+            : null;
+        const integrationData = asRecord(step.integrationData);
+        const router = isHexString(integrationData?.callToAddress)
+            ? integrationData.callToAddress
+            : null;
+        // Per-step cost = protocol fees + gas, both reported in United States dollars.
+        // Null when the provider reported neither, so the UI omits the hop's fee.
+        const protocolFeeUsd = sumUsdCosts(estimate?.feeCosts);
+        const gasCostUsd = sumUsdCosts(estimate?.gasCosts);
+        const stepCostUsd = protocolFeeUsd + gasCostUsd;
+        const feeUsd = stepCostUsd > 0 ? stepCostUsd : null;
+        // Gas alone, for route ranking (which charges gas on top of the paid-versus-
+        // delivered spread and must not double-count the protocol fees already baked
+        // into the quote's `fromAmount`). Null when no gas was reported.
+        const gasUsd = gasCostUsd > 0 ? gasCostUsd : null;
+        result.push({
+            kind,
+            label,
+            fromChainId,
+            toChainId,
+            fromToken,
+            toToken,
+            fromTokenSymbol,
+            toTokenSymbol,
+            fromTokenLogoUri,
+            toTokenLogoUri,
+            router,
+            estimatedOut,
+            feeUsd,
+            gasUsd,
+            providerLogoUri,
+        });
+    }
+    return result;
+};
+/**
+ * Parses one `{ currency, amount }` entry from Relay's `details.route`.
+ *
+ * @param value - a raw `inputCurrency`/`outputCurrency` value
+ * @returns the endpoint, or null when the chain id or address is unusable
+ */
+const relayRouteEndpoint = (value) => {
+    const entry = asRecord(value);
+    const currency = asRecord(entry?.currency);
+    if (!currency) {
+        return null;
+    }
+    const chainId = typeof currency.chainId === 'number' ? currency.chainId : null;
+    const address = typeof currency.address === 'string' ? currency.address : null;
+    // Without a chain and an identifier there is no leg to describe. Both are
+    // always present in Relay's verified shape; bail rather than invent one.
+    if (chainId === null || address === null) {
+        return null;
+    }
+    const metadata = asRecord(currency.metadata);
+    let amount = null;
+    if (typeof entry?.amount === 'string' && entry.amount !== '') {
+        try {
+            amount = BigInt(entry.amount);
+        }
+        catch {
+            amount = null;
+        }
+    }
+    return {
+        chainId,
+        address,
+        symbol: typeof currency.symbol === 'string' ? currency.symbol : null,
+        logoUri: typeof metadata?.logoURI === 'string' ? metadata.logoURI : null,
+        amount,
+    };
+};
+/**
+ * Reads a `{ amountUsd }` entry from Relay's `fees` object as a number.
+ * Relay reports dollar values as numeric strings; anything non-finite
+ * contributes nothing rather than poisoning the sum with `NaN`.
+ */
+const relayFeeUsd = (fees, key) => {
+    const fee = asRecord(fees?.[key]);
+    const amountUsd = typeof fee?.amountUsd === 'string' ? Number(fee.amountUsd) : Number.NaN;
+    return Number.isFinite(amountUsd) ? amountUsd : 0;
+};
+/** True when two endpoints are the same currency on the same chain. */
+const isSameEndpoint = (left, right) => left.chainId === right.chainId && left.address === right.address;
+/**
+ * Normalizes a Relay quote into the provider-agnostic `RouteStep[]` shape.
+ *
+ * Relay's `steps` array holds only OPERATIONAL steps (`approve` and `deposit`) —
+ * what the user signs, not where the funds go. The route itself lives in
+ * `details.route`, which describes the journey as an origin leg and a
+ * destination leg, each with an input and an output currency. Reading those four
+ * endpoints in order and emitting a step between each consecutive pair recovers
+ * the real path, so a Bitcoin origin renders as "Bitcoin → United States Dollar
+ * Coin on Ethereum" rather than as nothing at all.
+ *
+ * Consecutive endpoints that name the same currency on the same chain are
+ * collapsed, because Relay repeats an endpoint when a leg performs no
+ * conversion. A step's kind follows from its chains: crossing chains is a
+ * `bridge`, staying put is a `swap`. Relay reports no wrap/unwrap distinction,
+ * so none is invented.
+ *
+ * Costs are route-level in Relay's response, not per leg, so they are attached
+ * to the FIRST step — the one the user actually signs and pays at. `gasUsd`
+ * carries `fees.gas` alone (the origin transaction's gas, paid on top in the
+ * network's native token), while `feeUsd` adds the relayer and application fees
+ * on top of it, matching how the LI.FI normalizer splits the two. The relayer
+ * fee's `relayerGas`/`relayerService` components are deliberately NOT summed:
+ * they add up to `relayer` exactly, so counting them would double the fee.
+ *
+ * @param quote - a raw Relay quote response body
+ * @returns ordered list of normalized steps; empty when no route is present
+ */
+export const normalizeRelaySteps = (quote) => {
+    const details = asRecord(asRecord(quote)?.details);
+    const route = asRecord(details?.route);
+    if (!route) {
+        return [];
+    }
+    const origin = asRecord(route.origin);
+    const destination = asRecord(route.destination);
+    const endpoints = [
+        relayRouteEndpoint(origin?.inputCurrency),
+        relayRouteEndpoint(origin?.outputCurrency),
+        relayRouteEndpoint(destination?.inputCurrency),
+        relayRouteEndpoint(destination?.outputCurrency),
+    ].filter((endpoint) => endpoint !== null);
+    // Collapse repeats so a leg that converts nothing does not become a step.
+    const path = endpoints.filter((endpoint, index) => index === 0 || !isSameEndpoint(endpoint, endpoints[index - 1]));
+    if (path.length < 2) {
+        return [];
+    }
+    const fees = asRecord(asRecord(quote)?.fees);
+    const gasUsd = relayFeeUsd(fees, 'gas');
+    // `relayer` is the full relayer charge; its `relayerGas` and `relayerService`
+    // components sum to it exactly, so only the total is counted here.
+    const totalUsd = gasUsd + relayFeeUsd(fees, 'relayer') + relayFeeUsd(fees, 'app');
+    const result = [];
+    for (let index = 1; index < path.length; index += 1) {
+        const from = path[index - 1];
+        const to = path[index];
+        const kind = from.chainId === to.chainId ? 'swap' : 'bridge';
+        const isFirstStep = index === 1;
+        result.push({
+            kind,
+            label: kind === 'bridge'
+                ? `Bridge to ${chainDisplayName(to.chainId)}`
+                : `Swap on ${chainDisplayName(to.chainId)}`,
+            fromChainId: from.chainId,
+            toChainId: to.chainId,
+            fromToken: from.address,
+            toToken: to.address,
+            fromTokenSymbol: from.symbol,
+            toTokenSymbol: to.symbol,
+            // Relay's currency metadata carries the TOKEN's own image, which is the only
+            // one available for a non-Ethereum endpoint (Bitcoin, Solana, Tron, The Open
+            // Network) — the image service cannot key those by a hex address.
+            fromTokenLogoUri: from.logoUri,
+            toTokenLogoUri: to.logoUri,
+            // Relay's `router` field on a route leg names the service ("relay"), not a
+            // contract address, so there is no router address to surface for the leg.
+            router: null,
+            // Relay supplies a logo for the currency, not for a per-leg tool, so the
+            // consuming interface falls back to the provider tile. Deliberately null
+            // rather than passing a token image off as a service-provider image.
+            providerLogoUri: null,
+            estimatedOut: to.amount,
+            // Route-level costs land on the signed step; later legs run inside it.
+            feeUsd: isFirstStep && totalUsd > 0 ? totalUsd : null,
+            gasUsd: isFirstStep && gasUsd > 0 ? gasUsd : null,
+        });
+    }
+    return result;
+};

package/dist/routing/amounts.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The amount that actually LANDS on PulseChain for an aggregator candidate, net
+ * of the omnibridge crossing fee.
+ *
+ * The aggregator delivers `entryChainAmount` (the consolidated request's
+ * `toAmount`) onto the omnibridge entry chain, and the omnibridge entry call
+ * relays exactly that — but the omnibridge takes its foreign→home crossing fee on
+ * the way to PulseChain, so the user receives LESS than `entryChainAmount`. This
+ * nets that crossing fee out using the SDK's OWN fee primitives ({@link bridgeCost}
+ * and {@link amountAfterBridgeFee}) — the identical math the direct engine applies
+ * — so the displayed received amount is honest rather than overstated.
+ *
+ * The multiplexed (aggregator) swap fees are NOT subtracted here: the aggregator
+ * already quotes the source-chain `fromAmount` it needs to GUARANTEE
+ * `entryChainAmount` arrives, so those fees are already reflected in `fromAmount`.
+ * Only the omnibridge crossing fee remains to net out, which is this function's
+ * sole job.
+ *
+ * @param entryChainAmount - the amount arriving on the entry chain (request `toAmount`)
+ * @param omnibridgeFeePerEther - the omnibridge foreign→home fee rate (per 1e18), or null
+ * @returns the net amount delivered on PulseChain; equals `entryChainAmount` when the fee is unknown
+ */
+export declare const netDeliveredAmount: (entryChainAmount: bigint, omnibridgeFeePerEther: bigint | null) => bigint;
+/**
+ * Restates an amount in a different token's decimals, preserving the QUANTITY.
+ *
+ * This is the honest degraded answer when {@link valueEquivalentAmount} cannot
+ * price a conversion. Losing the price must not also lose the decimals: the two
+ * omnibridge anchors hold the same asset bridged two ways, and the only
+ * difference between them is where the decimal point sits. Returning an
+ * unadjusted amount across that gap is wrong by a factor of 10^12, which is the
+ * exact error the value conversion exists to prevent.
+ *
+ * Scaling DOWN truncates, and must — a six-decimal token cannot hold the twelve
+ * extra digits an eighteen-decimal one carries. The lost remainder is smaller
+ * than one base unit of the target.
+ *
+ * @param params.amount - the amount, in `fromDecimals` base units
+ * @param params.fromDecimals - the decimals the amount is currently expressed in
+ * @param params.toDecimals - the decimals to restate it in
+ * @returns the same quantity, in `toDecimals` base units
+ */
+export declare const restateInDecimals: ({ amount, fromDecimals, toDecimals, }: {
+    amount: bigint;
+    fromDecimals: number;
+    toDecimals: number;
+}) => bigint;
+/**
+ * Converts `amount` of a source token into the base-unit amount of a TARGET token
+ * carrying the SAME United States dollar value:
+ *
+ *   valueUsd     = amount / 10^fromDecimals × fromPrice
+ *   targetAmount = valueUsd / toPrice × 10^toDecimals
+ *
+ * This is what lets the two omnibridge entry points be quoted for the SAME VALUE
+ * even when their anchor tokens differ in decimals — a PulseChain-bridged
+ * stablecoin is 6 decimals when bridged from Ethereum but 18 from Binance Smart
+ * Chain. Feeding one raw integer to both targeted quantities ~10^12 apart, so the
+ * routes were not comparable and the higher-decimal entry won on a bigger NUMBER
+ * rather than more value. Targeting equal value in each anchor's own decimals
+ * restores a fair, decimals-correct comparison.
+ *
+ * Returns null when either price is missing or non-positive, the scaled value is
+ * not finite, or the target cannot be parsed — the caller then has no
+ * value-equivalent target and must fall back rather than quote a bogus amount.
+ *
+ * @param params.amount - the source amount, in `fromDecimals` base units
+ * @param params.fromDecimals - the source token's decimals
+ * @param params.fromPrice - the source token's per-token United States dollar price, or null
+ * @param params.toDecimals - the target token's decimals
+ * @param params.toPrice - the target token's per-token United States dollar price, or null
+ * @returns the value-equivalent amount in the target token's base units, or null
+ */
+export declare const valueEquivalentAmount: ({ amount, fromDecimals, fromPrice, toDecimals, toPrice, }: {
+    amount: bigint;
+    fromDecimals: number;
+    fromPrice: number | null;
+    toDecimals: number;
+    toPrice: number | null;
+}) => bigint | null;

package/dist/routing/amounts.js

@@ -0,0 +1,120 @@
+import { formatUnits, parseUnits } from 'viem';
+import { amountAfterBridgeFee, bridgeCost } from '../settings.js';
+/**
+ * The amount that actually LANDS on PulseChain for an aggregator candidate, net
+ * of the omnibridge crossing fee.
+ *
+ * The aggregator delivers `entryChainAmount` (the consolidated request's
+ * `toAmount`) onto the omnibridge entry chain, and the omnibridge entry call
+ * relays exactly that — but the omnibridge takes its foreign→home crossing fee on
+ * the way to PulseChain, so the user receives LESS than `entryChainAmount`. This
+ * nets that crossing fee out using the SDK's OWN fee primitives ({@link bridgeCost}
+ * and {@link amountAfterBridgeFee}) — the identical math the direct engine applies
+ * — so the displayed received amount is honest rather than overstated.
+ *
+ * The multiplexed (aggregator) swap fees are NOT subtracted here: the aggregator
+ * already quotes the source-chain `fromAmount` it needs to GUARANTEE
+ * `entryChainAmount` arrives, so those fees are already reflected in `fromAmount`.
+ * Only the omnibridge crossing fee remains to net out, which is this function's
+ * sole job.
+ *
+ * @param entryChainAmount - the amount arriving on the entry chain (request `toAmount`)
+ * @param omnibridgeFeePerEther - the omnibridge foreign→home fee rate (per 1e18), or null
+ * @returns the net amount delivered on PulseChain; equals `entryChainAmount` when the fee is unknown
+ */
+export const netDeliveredAmount = (entryChainAmount, omnibridgeFeePerEther) => {
+    // Defensive: the omnibridge percentage math runs ONLY when both operands are
+    // true bigints. A non-bigint fee (a value rehydrated from storage as a string,
+    // the project's documented BigInt-serialization gotcha) would throw inside
+    // `bridgeCost`'s mixed-type multiplication, so fall back to the un-netted
+    // entry-chain amount rather than crash the render. The `typeof` guards intentionally
+    // outlive the static `bigint` types because the runtime value can violate them.
+    if (typeof entryChainAmount !== 'bigint' || typeof omnibridgeFeePerEther !== 'bigint') {
+        return entryChainAmount;
+    }
+    const cost = bridgeCost({ amountToBridge: entryChainAmount, bridgeFee: omnibridgeFeePerEther });
+    const net = amountAfterBridgeFee({ amountToBridge: entryChainAmount, bridgeCost: cost });
+    return net ?? entryChainAmount;
+};
+/**
+ * Restates an amount in a different token's decimals, preserving the QUANTITY.
+ *
+ * This is the honest degraded answer when {@link valueEquivalentAmount} cannot
+ * price a conversion. Losing the price must not also lose the decimals: the two
+ * omnibridge anchors hold the same asset bridged two ways, and the only
+ * difference between them is where the decimal point sits. Returning an
+ * unadjusted amount across that gap is wrong by a factor of 10^12, which is the
+ * exact error the value conversion exists to prevent.
+ *
+ * Scaling DOWN truncates, and must — a six-decimal token cannot hold the twelve
+ * extra digits an eighteen-decimal one carries. The lost remainder is smaller
+ * than one base unit of the target.
+ *
+ * @param params.amount - the amount, in `fromDecimals` base units
+ * @param params.fromDecimals - the decimals the amount is currently expressed in
+ * @param params.toDecimals - the decimals to restate it in
+ * @returns the same quantity, in `toDecimals` base units
+ */
+export const restateInDecimals = ({ amount, fromDecimals, toDecimals, }) => {
+    if (fromDecimals === toDecimals)
+        return amount;
+    if (toDecimals > fromDecimals)
+        return amount * 10n ** BigInt(toDecimals - fromDecimals);
+    return amount / 10n ** BigInt(fromDecimals - toDecimals);
+};
+/**
+ * Converts `amount` of a source token into the base-unit amount of a TARGET token
+ * carrying the SAME United States dollar value:
+ *
+ *   valueUsd     = amount / 10^fromDecimals × fromPrice
+ *   targetAmount = valueUsd / toPrice × 10^toDecimals
+ *
+ * This is what lets the two omnibridge entry points be quoted for the SAME VALUE
+ * even when their anchor tokens differ in decimals — a PulseChain-bridged
+ * stablecoin is 6 decimals when bridged from Ethereum but 18 from Binance Smart
+ * Chain. Feeding one raw integer to both targeted quantities ~10^12 apart, so the
+ * routes were not comparable and the higher-decimal entry won on a bigger NUMBER
+ * rather than more value. Targeting equal value in each anchor's own decimals
+ * restores a fair, decimals-correct comparison.
+ *
+ * Returns null when either price is missing or non-positive, the scaled value is
+ * not finite, or the target cannot be parsed — the caller then has no
+ * value-equivalent target and must fall back rather than quote a bogus amount.
+ *
+ * @param params.amount - the source amount, in `fromDecimals` base units
+ * @param params.fromDecimals - the source token's decimals
+ * @param params.fromPrice - the source token's per-token United States dollar price, or null
+ * @param params.toDecimals - the target token's decimals
+ * @param params.toPrice - the target token's per-token United States dollar price, or null
+ * @returns the value-equivalent amount in the target token's base units, or null
+ */
+export const valueEquivalentAmount = ({ amount, fromDecimals, fromPrice, toDecimals, toPrice, }) => {
+    if (fromPrice === null || toPrice === null)
+        return null;
+    if (!(fromPrice > 0) || !(toPrice > 0))
+        return null;
+    // Equal prices make this a pure change of decimals, and integer rescaling is
+    // EXACT where the double round trip is not. `39.3` is not representable as a
+    // double, so `toFixed(18)` writes 39.299999999999997158 and the conversion
+    // comes back 2842 base units short of the 39.3 that went in. At the same
+    // decimals it lands one unit out (0.008802 returns as 8802000000000001).
+    //
+    // Both are negligible in value and neither is a reason to convert at all: with
+    // one price on both sides there is no value question to answer, only a decimal
+    // point to move. Moving it in integers keeps the same input producing the same
+    // target.
+    if (fromPrice === toPrice)
+        return restateInDecimals({ amount, fromDecimals, toDecimals });
+    const valueUsd = Number(formatUnits(amount, fromDecimals)) * fromPrice;
+    if (!Number.isFinite(valueUsd))
+        return null;
+    const targetWhole = valueUsd / toPrice;
+    if (!Number.isFinite(targetWhole) || targetWhole < 0)
+        return null;
+    try {
+        return parseUnits(targetWhole.toFixed(toDecimals), toDecimals);
+    }
+    catch {
+        return null;
+    }
+};