@gibs/bridge-sdk 1.13.0 → 1.17.0

package/dist/cjs/routing/carriers/wrap.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWrapCarrier = void 0;
+const viem_1 = require("viem");
+const config_js_1 = require("../../config.js");
+const graph_js_1 = require("../search/graph.js");
+/**
+ * Native-coin wrap/unwrap (PLS <-> WPLS on PulseChain, and the same pair on
+ * every other Ethereum-Virtual-Machine chain the search graph touches — ETH
+ * <-> WETH, BNB <-> WBNB) as a plug-in `Carrier` for `@gibs/quotes`'s
+ * route-search engine. GIBS-SPECIFIC in the sense `omnibridge.ts`/`pulsex.ts`
+ * are (see `omnibridge.ts`'s head doc for why this returns a plain object
+ * shaped like `Carrier` rather than importing that type) — though the
+ * carrier itself names no chain: it derives every wrap pair from
+ * `config.ts`'s own `nativeAssetOut` map, so a chain added there gains a
+ * wrap edge with no change here.
+ *
+ * WHY THIS IS A SEPARATE CARRIER FROM PulseX. `pulsex.ts`'s own
+ * `readPulseXAmountOut` (via `pulseXSwapPathForEdge` in
+ * `packages/ui/src/lib/state/useRouteSearch.ts`) quotes native Pulse AS
+ * Wrapped Pulse — both map to the same `quotePathAddress` — so a PLS<->WPLS
+ * pair collapses to "no swap to quote" and PulseX has never carried it.
+ * There is no PulseX POOL for native-versus-wrapped; it is a 1:1 contract
+ * call (`deposit()`/`withdraw(uint256)`), not a trade, so it needed its own
+ * carrier rather than a PulseX special case.
+ *
+ * SENDER: `'swap'`, THE SAME NAME `pulsex.ts` USES — the reader's own
+ * connected wallet signs a `deposit()`/`withdraw(uint256)` call on the
+ * wrapped token's own contract (WETH9-style; confirmed present on WPLS by
+ * bytecode selector 2026-09-24), exactly the wallet a same-chain PulseX swap
+ * already uses. WHETHER `settings.ts`'s EXISTING swap-transaction builder
+ * (`pulseXSwapTransactionInputs`) CAN BUILD THIS CALL: NO, not without a
+ * change there — that builder only ever targets a PulseX ROUTER address and
+ * encodes `swapExact*` calldata; a wrap needs `to` = the wrapped token
+ * itself and `data` = plain `deposit()`/`withdraw(amount)` calldata, which
+ * is a different (and simpler) shape. Sharing the `'swap'` sender name says
+ * "the same wallet, the same signing step in the flow" — it does not claim
+ * the existing builder already emits this calldata. Building that call is
+ * `settings.ts`'s job, out of this carrier's scope; this module answers only
+ * the route-search question ("what does this edge deliver, exactly").
+ */
+/**
+ * Whether this carrier can wrap/unwrap directly between `from` and `to`:
+ * same Ethereum-Virtual-Machine chain, and the two addresses are EXACTLY the
+ * zero-address/wrapped-native pair `config.ts`'s `nativeAssetOut` names for
+ * that chain — nothing else, so a plain token pair that merely happens to
+ * share a chain is never mistaken for a wrap.
+ */
+const wrapCarries = (from, to) => {
+    if (from.ecosystem !== 'evm' || to.ecosystem !== 'evm')
+        return false;
+    if (from.chainId !== to.chainId)
+        return false;
+    const wrappedNativeAddress = config_js_1.nativeAssetOut[(0, config_js_1.toChain)(from.chainId)];
+    if (wrappedNativeAddress === undefined)
+        return false;
+    const wrapped = (0, viem_1.getAddress)(wrappedNativeAddress).toLowerCase();
+    const fromAddress = from.address.toLowerCase();
+    const toAddress = to.address.toLowerCase();
+    const fromIsNative = fromAddress === viem_1.zeroAddress;
+    const toIsNative = toAddress === viem_1.zeroAddress;
+    if (fromIsNative)
+        return toAddress === wrapped;
+    if (toIsNative)
+        return fromAddress === wrapped;
+    return false;
+};
+/** Every wrap/unwrap edge is worth exactly `amountIn`, in `edge.to`'s base units — native and wrapped share the same decimals on every chain this carrier has ever seen (18, both sides, everywhere `nativeAssetOut` names). */
+const wrapExact = (edge, amountIn) => {
+    if (!wrapCarries(edge.from, edge.to))
+        return null;
+    return { outcome: 'delivered', deliveredAmount: amountIn };
+};
+/**
+ * Builds the native wrap/unwrap carrier as a plug-in.
+ *
+ * NO OPTIONS, NO `prepare`. There is no local read to batch — a wrap has no
+ * minimum, no maximum, no fee rate and no reserve to be wrong about; it is a
+ * pure 1:1 identity over every chain `config.ts` names a wrapped-native
+ * token for. `exact` alone is total over every edge this carrier offers.
+ *
+ * @returns the carrier — `id: 'wrap'`
+ */
+const createWrapCarrier = () => {
+    const edgesFrom = (from, to) => {
+        if ((0, graph_js_1.assetNodeKey)(from) === (0, graph_js_1.assetNodeKey)(to))
+            return [];
+        if (!wrapCarries(from, to))
+            return [];
+        return [{ carrier: 'wrap', from, to, fusesNext: false, origin: 'wallet', floors: [] }];
+    };
+    const ask = async ({ edge, inputAmount }) => {
+        const result = wrapExact(edge, inputAmount);
+        if (result === null || result.outcome === 'refused') {
+            return { ok: false, refusal: { kind: 'cannot-carry', reason: 'not a native/wrapped pair', minimumAmount: null } };
+        }
+        return {
+            ok: true,
+            deliveredAmount: result.deliveredAmount,
+            // 1:1, always — there is no slippage to guarantee against.
+            minimumDeliveredAmount: result.deliveredAmount,
+            claimedDurationSeconds: 0,
+        };
+    };
+    return {
+        id: 'wrap',
+        edgesFrom,
+        ask,
+        exact: wrapExact,
+        isRateLimited: false,
+        // A `deposit()`/`withdraw()` call requires the reader's own wallet
+        // signature — never a by-hand deposit.
+        depositMode: 'wallet-signed',
+        sender: 'swap',
+        // A same-chain call settles with the transaction itself.
+        settlementSeconds: 0,
+    };
+};
+exports.createWrapCarrier = createWrapCarrier;

package/dist/cjs/routing/composed-route-quality.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Whether a composed multi-signature route is good enough to offer at all.
+ *
+ * WHY A ROUTE NEEDS A GATE THAT A SINGLE CROSSING DOES NOT. A one-signature
+ * route that turns out badly costs the reader one transaction and they still
+ * hold something they chose. A composed route — an aggregator leg, then an
+ * omnibridge crossing, then a swap — strands them between signatures: after
+ * the first they hold an anchor token on a chain they did not ask for, and the
+ * only way out is to pay again. So a cheap first leg followed by a bad swap is
+ * worse than the route it replaced, and the difference has to be found BEFORE
+ * the route is listed rather than after the reader has signed.
+ *
+ * NOTHING HERE COSTS A REQUEST. Both figures the verdict reads are already in
+ * hand when a composer runs: the swap's price impact comes from the on-chain
+ * `getAmountsOut` pair the estimate already fetched, and the two dollar values
+ * come from the route's own basis. The gate is free, which is why it can run
+ * on every route rather than only on suspicious ones.
+ */
+/**
+ * The price impact above which a composed route is withdrawn, in percent.
+ *
+ * MEASURED RATHER THAN CHOSEN. Across the anchor and size combinations swept
+ * on 2026-09-21 — bridged wrapped ether, USD Coin, DAI and USDT into wrapped
+ * PulseChain coin, at roughly forty and one hundred and forty United States
+ * dollars — the impact ran from 0.008 percent to 0.037 percent, with bridged
+ * USDT the one outlier at 0.34 to 0.37 percent. Three percent is two orders of
+ * magnitude above the normal case and an order above the worst observed, so it
+ * cannot fire on an ordinary route; and it is still far below the point where
+ * a reader is quietly losing real money on a leg they cannot undo.
+ *
+ * See `docs/near-intents-conversion-composition.md` for the full sweep.
+ */
+export declare const COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT = 3;
+/**
+ * The end-to-end value loss above which a composed route is withdrawn, in
+ * percent of what the reader pays.
+ *
+ * A SECOND TEST BECAUSE THE FIRST CAN READ FINE ON A BROKEN POOL. Price impact
+ * is measured against a marginal reference quote taken from the same pool, so
+ * a pool that is uniformly mispriced — a stale pair, a pair holding almost
+ * nothing — reports a small impact while paying out far less than the tokens
+ * going in are worth. Only comparing the two ends of the journey catches that.
+ *
+ * Measured whole-journey loss on the same sweep ran from 0.81 to 1.36 percent,
+ * of which the swap fee alone is 0.29. Five percent leaves every observed
+ * route untouched and still stops a route that is quietly eating a twentieth
+ * of the reader's money.
+ */
+export declare const COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT = 5;
+/**
+ * The end-to-end value GAIN above which a composed route is withdrawn, in
+ * percent of what the reader pays.
+ *
+ * A ROUTE CANNOT MAKE MONEY. Every leg charges a fee, so a route that
+ * delivers more value than it takes says one of its figures is wrong. Only a
+ * disagreement between the two price feeds can make a gain look real, and the
+ * value-loss ceiling already trusts those feeds to within the same five
+ * percent. So the bound is symmetric with
+ * {@link COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT}.
+ *
+ * THE DEFECT THIS STOPS. On 2026-10-03 the engine served 0.0002 BNB to HEX at
+ * 495,256 HEX, about seven thousand times the rate of the next tier. The
+ * value-loss test read that as a loss of minus seven hundred thousand percent
+ * and passed it. A PulseX hop rescaled from an upstream live answer keeps the
+ * price impact measured at its original, smaller input
+ * (`recomposePath` in `@gibs/quotes`'s `search/waves.ts`), so the impact test
+ * cannot see an inflated amount either. Only the two ends of the journey can.
+ */
+export declare const COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT = 5;
+/**
+ * The verdict on one composed route.
+ *
+ * THREE STATES RATHER THAN A BOOLEAN, because "we have not priced this yet"
+ * and "we priced it and it is bad" are different facts and a caller must be
+ * able to act differently on them. Collapsing them would either hide a route
+ * that is merely still loading or offer one nobody has checked.
+ */
+export type ComposedRouteVerdict = {
+    readonly state: 'acceptable';
+} | {
+    readonly state: 'unknown';
+    readonly missing: 'price-impact' | 'route-value';
+} | {
+    readonly state: 'rejected';
+    readonly reason: 'price-impact' | 'value-loss' | 'value-gain';
+    /** The measured figure, in percent, that failed its ceiling. */
+    readonly measuredPercent: number;
+    /** The ceiling it failed. */
+    readonly ceilingPercent: number;
+};
+/**
+ * Judges a composed route against its three ceilings.
+ *
+ * Checks price impact first, then value loss, then value gain. Impact names
+ * the specific leg at fault, while the two value tests only say the journey as
+ * a whole went wrong, so impact is the more useful answer when several fail.
+ * In the measured percent of a `'value-gain'` rejection, the gain is a
+ * positive number.
+ *
+ * @param options.priceImpactPercent - the swap leg's price impact, from the
+ *   estimate's marginal reference quote; null when not yet quoted
+ * @param options.paidUsdValue - what the reader spends at the origin, in
+ *   United States dollars; null when unpriced
+ * @param options.deliveredUsdValue - what the route delivers, valued on the
+ *   SAME basis as `paidUsdValue`; null when unpriced
+ * @returns the verdict
+ */
+export declare const assessComposedRoute: ({ priceImpactPercent, paidUsdValue, deliveredUsdValue, }: {
+    priceImpactPercent: number | null | undefined;
+    paidUsdValue: number | null | undefined;
+    deliveredUsdValue: number | null | undefined;
+}) => ComposedRouteVerdict;
+/**
+ * Whether a composed route may be listed on the strip.
+ *
+ * ONLY AN EXPLICIT PASS LISTS THE ROUTE. An unknown verdict withholds it, the
+ * same as a rejection, because a three-signature route nobody has checked is
+ * the case this gate exists for. The two remain distinct in
+ * {@link ComposedRouteVerdict} so a surface can tell the reader "still
+ * pricing" rather than "no route", which a boolean alone could not.
+ *
+ * @param verdict - the verdict from {@link assessComposedRoute}
+ * @returns true only when the route passed every ceiling
+ */
+export declare const composedRouteMayBeOffered: (verdict: ComposedRouteVerdict) => boolean;

package/dist/cjs/routing/composed-route-quality.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composedRouteMayBeOffered = exports.assessComposedRoute = exports.COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT = exports.COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT = exports.COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT = void 0;
+/**
+ * Whether a composed multi-signature route is good enough to offer at all.
+ *
+ * WHY A ROUTE NEEDS A GATE THAT A SINGLE CROSSING DOES NOT. A one-signature
+ * route that turns out badly costs the reader one transaction and they still
+ * hold something they chose. A composed route — an aggregator leg, then an
+ * omnibridge crossing, then a swap — strands them between signatures: after
+ * the first they hold an anchor token on a chain they did not ask for, and the
+ * only way out is to pay again. So a cheap first leg followed by a bad swap is
+ * worse than the route it replaced, and the difference has to be found BEFORE
+ * the route is listed rather than after the reader has signed.
+ *
+ * NOTHING HERE COSTS A REQUEST. Both figures the verdict reads are already in
+ * hand when a composer runs: the swap's price impact comes from the on-chain
+ * `getAmountsOut` pair the estimate already fetched, and the two dollar values
+ * come from the route's own basis. The gate is free, which is why it can run
+ * on every route rather than only on suspicious ones.
+ */
+/**
+ * The price impact above which a composed route is withdrawn, in percent.
+ *
+ * MEASURED RATHER THAN CHOSEN. Across the anchor and size combinations swept
+ * on 2026-09-21 — bridged wrapped ether, USD Coin, DAI and USDT into wrapped
+ * PulseChain coin, at roughly forty and one hundred and forty United States
+ * dollars — the impact ran from 0.008 percent to 0.037 percent, with bridged
+ * USDT the one outlier at 0.34 to 0.37 percent. Three percent is two orders of
+ * magnitude above the normal case and an order above the worst observed, so it
+ * cannot fire on an ordinary route; and it is still far below the point where
+ * a reader is quietly losing real money on a leg they cannot undo.
+ *
+ * See `docs/near-intents-conversion-composition.md` for the full sweep.
+ */
+exports.COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT = 3;
+/**
+ * The end-to-end value loss above which a composed route is withdrawn, in
+ * percent of what the reader pays.
+ *
+ * A SECOND TEST BECAUSE THE FIRST CAN READ FINE ON A BROKEN POOL. Price impact
+ * is measured against a marginal reference quote taken from the same pool, so
+ * a pool that is uniformly mispriced — a stale pair, a pair holding almost
+ * nothing — reports a small impact while paying out far less than the tokens
+ * going in are worth. Only comparing the two ends of the journey catches that.
+ *
+ * Measured whole-journey loss on the same sweep ran from 0.81 to 1.36 percent,
+ * of which the swap fee alone is 0.29. Five percent leaves every observed
+ * route untouched and still stops a route that is quietly eating a twentieth
+ * of the reader's money.
+ */
+exports.COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT = 5;
+/**
+ * The end-to-end value GAIN above which a composed route is withdrawn, in
+ * percent of what the reader pays.
+ *
+ * A ROUTE CANNOT MAKE MONEY. Every leg charges a fee, so a route that
+ * delivers more value than it takes says one of its figures is wrong. Only a
+ * disagreement between the two price feeds can make a gain look real, and the
+ * value-loss ceiling already trusts those feeds to within the same five
+ * percent. So the bound is symmetric with
+ * {@link COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT}.
+ *
+ * THE DEFECT THIS STOPS. On 2026-10-03 the engine served 0.0002 BNB to HEX at
+ * 495,256 HEX, about seven thousand times the rate of the next tier. The
+ * value-loss test read that as a loss of minus seven hundred thousand percent
+ * and passed it. A PulseX hop rescaled from an upstream live answer keeps the
+ * price impact measured at its original, smaller input
+ * (`recomposePath` in `@gibs/quotes`'s `search/waves.ts`), so the impact test
+ * cannot see an inflated amount either. Only the two ends of the journey can.
+ */
+exports.COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT = 5;
+/**
+ * Judges a composed route against its three ceilings.
+ *
+ * Checks price impact first, then value loss, then value gain. Impact names
+ * the specific leg at fault, while the two value tests only say the journey as
+ * a whole went wrong, so impact is the more useful answer when several fail.
+ * In the measured percent of a `'value-gain'` rejection, the gain is a
+ * positive number.
+ *
+ * @param options.priceImpactPercent - the swap leg's price impact, from the
+ *   estimate's marginal reference quote; null when not yet quoted
+ * @param options.paidUsdValue - what the reader spends at the origin, in
+ *   United States dollars; null when unpriced
+ * @param options.deliveredUsdValue - what the route delivers, valued on the
+ *   SAME basis as `paidUsdValue`; null when unpriced
+ * @returns the verdict
+ */
+const assessComposedRoute = ({ priceImpactPercent, paidUsdValue, deliveredUsdValue, }) => {
+    if (typeof priceImpactPercent !== 'number' || !Number.isFinite(priceImpactPercent)) {
+        return { state: 'unknown', missing: 'price-impact' };
+    }
+    if (priceImpactPercent > exports.COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT) {
+        return {
+            state: 'rejected',
+            reason: 'price-impact',
+            measuredPercent: priceImpactPercent,
+            ceilingPercent: exports.COMPOSED_ROUTE_MAX_PRICE_IMPACT_PERCENT,
+        };
+    }
+    const bothValuesKnown = typeof paidUsdValue === 'number' &&
+        Number.isFinite(paidUsdValue) &&
+        paidUsdValue > 0 &&
+        typeof deliveredUsdValue === 'number' &&
+        Number.isFinite(deliveredUsdValue);
+    if (!bothValuesKnown) {
+        return { state: 'unknown', missing: 'route-value' };
+    }
+    const lossPercent = ((paidUsdValue - deliveredUsdValue) / paidUsdValue) * 100;
+    if (lossPercent > exports.COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT) {
+        return {
+            state: 'rejected',
+            reason: 'value-loss',
+            measuredPercent: lossPercent,
+            ceilingPercent: exports.COMPOSED_ROUTE_MAX_VALUE_LOSS_PERCENT,
+        };
+    }
+    const gainPercent = -lossPercent;
+    if (gainPercent > exports.COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT) {
+        return {
+            state: 'rejected',
+            reason: 'value-gain',
+            measuredPercent: gainPercent,
+            ceilingPercent: exports.COMPOSED_ROUTE_MAX_VALUE_GAIN_PERCENT,
+        };
+    }
+    return { state: 'acceptable' };
+};
+exports.assessComposedRoute = assessComposedRoute;
+/**
+ * Whether a composed route may be listed on the strip.
+ *
+ * ONLY AN EXPLICIT PASS LISTS THE ROUTE. An unknown verdict withholds it, the
+ * same as a rejection, because a three-signature route nobody has checked is
+ * the case this gate exists for. The two remain distinct in
+ * {@link ComposedRouteVerdict} so a surface can tell the reader "still
+ * pricing" rather than "no route", which a boolean alone could not.
+ *
+ * @param verdict - the verdict from {@link assessComposedRoute}
+ * @returns true only when the route passed every ceiling
+ */
+const composedRouteMayBeOffered = (verdict) => verdict.state === 'acceptable';
+exports.composedRouteMayBeOffered = composedRouteMayBeOffered;

package/dist/cjs/routing/entry-chain-anchor.d.ts

@@ -0,0 +1,88 @@
+import type { Token } from '../types.js';
+/**
+ * Which anchor tokens a non-executing aggregator may deliver on an omnibridge
+ * entry chain, and what the reader's own crossing signature then does with
+ * each one.
+ *
+ * WHY THE ANCHOR HAS TO BE A CHOICE RATHER THAN A DERIVATION. A two-signature
+ * route quotes towards one entry-chain token, taken straight from the
+ * destination pair. For a native-PulseChain destination that token is
+ * WRAPPED ether, because the omnibridge home list holds no entry for the
+ * native coin at all — measured on 2026-09-21, 657 Ethereum-side entries and
+ * not one at the zero address — so the pair a native destination resolves to
+ * is `WETH ↔ WETH from Ethereum`.
+ *
+ * NEAR Intents has NO LIQUIDITY IN WRAPPED ETHER ON ETHEREUM. Measured at
+ * 0.015, 0.05, 0.2 and 0.5 ether of input, every request answered
+ * `No liquidity available`. It carries the NATIVE coin on the same chain with
+ * plenty. So the one derived anchor is the one anchor the service cannot
+ * price, the quote is refused, and the route withdraws in silence — which is
+ * the correct response to a refusal and is also what hid this from us.
+ *
+ * WRAPPED NATIVE AND THE NATIVE COIN LAND IN THE SAME PLACE, which is what
+ * makes the substitution safe rather than merely convenient. The mediator's
+ * native router wraps on the way in: `wrapAndRelayTokens` takes the coin as
+ * transaction value and the crossing mints the SAME PulseChain token the
+ * wrapped entry would have minted. See `settings.ts`, the
+ * `assetIn.address === zeroAddress` branch. So swapping one anchor for the
+ * other changes what the aggregator delivers and changes nothing downstream.
+ *
+ * IT IS ALSO CHEAPER AND SHORTER, on both legs. Measured from Base native
+ * ether on 2026-09-21, one request batch per size:
+ *
+ * | anchor on Ethereum | 0.015 ether | 0.05 ether | 0.2 ether |
+ * | ------------------ | ----------- | ---------- | --------- |
+ * | native ether       | 0.494%      | 0.330%     | 0.278%    |
+ * | USD Coin           | 1.037%      | 0.651%     | 0.509%    |
+ * | Tether             | 1.052%      | 0.665%     | 0.506%    |
+ * | wrapped ether      | refused     | refused    | refused   |
+ *
+ * And the native coin needs no allowance, so its crossing is ONE signature
+ * where an entry-chain token's is an approval followed by a relay.
+ */
+/** What the reader's crossing signature calls with a given anchor. */
+export type EntryChainCrossingCall = 
+/** Native coin sent as transaction value; the router wraps and relays it. */
+'wrapAndRelayTokens'
+/** An entry-chain token handed to the mediator, which needs an allowance first. */
+ | 'relayTokens';
+/** One anchor the aggregator may be asked to deliver, and its consequences. */
+export type EntryChainAnchor = {
+    /** The token the aggregator delivers into the reader's own wallet. */
+    readonly token: Token;
+    /** What the reader's crossing signature calls with it. */
+    readonly crossingCall: EntryChainCrossingCall;
+    /**
+     * Whether the crossing needs a separate approval transaction first, which
+     * is an EXTRA signature on a route that already asks for several.
+     */
+    readonly requiresApproval: boolean;
+    /** The PulseChain token the crossing mints. Identical across every anchor here. */
+    readonly landsAs: Token;
+};
+/**
+ * Builds the ordered anchor list for one destination pair, cheapest and
+ * shortest first.
+ *
+ * The list is ordered, not ranked: a caller asks the aggregator for the first
+ * entry and moves to the next only on a refusal. That keeps the cost at ONE
+ * vendor request in the ordinary case, which matters against a limit of
+ * twelve hundred requests per sixty seconds.
+ *
+ * The substitution is narrow ON PURPOSE. Only the chain's wrapped native
+ * asset gains a second anchor, because only the native coin mints the same
+ * PulseChain token. A USD Coin pair does not gain an ether anchor here —
+ * ether would land as bridged ether, a different token, needing a different
+ * swap path. That is a different DESTINATION PAIR, and choosing between pairs
+ * is made by the route engine, which holds every destination pair.
+ *
+ * @param options.entryChainToken - the destination pair's entry-chain side
+ * @param options.pulsechainToken - the destination pair's PulseChain side
+ * @param options.entryChainId - the omnibridge entry chain's decimal id
+ * @returns the anchors to try, in order; never empty
+ */
+export declare const entryChainAnchorsForPair: ({ entryChainToken, pulsechainToken, entryChainId, }: {
+    entryChainToken: Token;
+    pulsechainToken: Token;
+    entryChainId: number;
+}) => readonly EntryChainAnchor[];

package/dist/cjs/routing/entry-chain-anchor.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.entryChainAnchorsForPair = void 0;
+const viem_1 = require("viem");
+const config_js_1 = require("../config.js");
+const ecosystems_js_1 = require("../ecosystems.js");
+/**
+ * Builds the ordered anchor list for one destination pair, cheapest and
+ * shortest first.
+ *
+ * The list is ordered, not ranked: a caller asks the aggregator for the first
+ * entry and moves to the next only on a refusal. That keeps the cost at ONE
+ * vendor request in the ordinary case, which matters against a limit of
+ * twelve hundred requests per sixty seconds.
+ *
+ * The substitution is narrow ON PURPOSE. Only the chain's wrapped native
+ * asset gains a second anchor, because only the native coin mints the same
+ * PulseChain token. A USD Coin pair does not gain an ether anchor here —
+ * ether would land as bridged ether, a different token, needing a different
+ * swap path. That is a different DESTINATION PAIR, and choosing between pairs
+ * is made by the route engine, which holds every destination pair.
+ *
+ * @param options.entryChainToken - the destination pair's entry-chain side
+ * @param options.pulsechainToken - the destination pair's PulseChain side
+ * @param options.entryChainId - the omnibridge entry chain's decimal id
+ * @returns the anchors to try, in order; never empty
+ */
+const entryChainAnchorsForPair = ({ entryChainToken, pulsechainToken, entryChainId, }) => {
+    const pairAnchor = {
+        token: entryChainToken,
+        crossingCall: 'relayTokens',
+        requiresApproval: true,
+        landsAs: pulsechainToken,
+    };
+    const entryChain = (0, config_js_1.toChain)(entryChainId);
+    // `nativeAssetOut` is typed as a total record and is not one — `toChain` is a
+    // cast, so an unmapped chain id yields a key that indexes to undefined. The
+    // runtime check outlives the static type on purpose.
+    const wrappedNativeAddress = config_js_1.nativeAssetOut[entryChain];
+    if (wrappedNativeAddress === undefined ||
+        !(0, ecosystems_js_1.sameAddress)(entryChainToken.address, wrappedNativeAddress, 'evm')) {
+        return [pairAnchor];
+    }
+    const nativeAnchor = {
+        token: {
+            // Decimals and name come from the WRAPPED token rather than from a
+            // constant, because the wrapped asset mirrors its coin exactly and a
+            // hard-coded eighteen would be a second source of the same fact.
+            ...entryChainToken,
+            address: viem_1.zeroAddress,
+            symbol: config_js_1.nativeTokenSymbol[entryChain] ?? entryChainToken.symbol,
+        },
+        crossingCall: 'wrapAndRelayTokens',
+        requiresApproval: false,
+        landsAs: pulsechainToken,
+    };
+    return [nativeAnchor, pairAnchor];
+};
+exports.entryChainAnchorsForPair = entryChainAnchorsForPair;

package/dist/cjs/routing/format.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Formats a United States dollar number to a cent-precise string ("1,234.50",
+ * or "1.234,50" in German). No leading currency symbol — callers prepend it
+ * where the design needs one. The single source of truth shared by the raw
+ * producers (cent-rounding) and the display adapter (final formatting).
+ *
+ * `locale` defaults to `'en-US'` so every caller that does not read the
+ * reader's own language — the raw producers, and every existing test —
+ * keeps today's exact string. THE DISPLAY ADAPTER (`toRouteView.ts`) is the
+ * one caller that should pass the reader's own Lingui locale (`i18n.locale`):
+ * without it, the route strip's dollar figures stayed English-formatted
+ * inside every other translated screen, the one number on the page that
+ * never adopted the reader's language. The digit count never moves — only
+ * `toLocaleString`'s grouping and decimal separators do, per
+ * `minimumFractionDigits`/`maximumFractionDigits` staying pinned at 2.
+ *
+ * @param value - the United States dollar amount as a number
+ * @param locale - a BCP 47 locale tag to format with; defaults to `'en-US'`
+ * @returns the formatted two-decimal string, without a leading `$`
+ */
+export declare const formatUsd: (value: number, locale?: string) => string;
+/**
+ * Nullable {@link formatUsd}: null/undefined pass through as null so an unpriced
+ * value renders as absent rather than "0.00".
+ *
+ * @param value - the United States dollar amount, or null/undefined when unknown
+ * @param locale - a BCP 47 locale tag to format with; defaults to `'en-US'`
+ * @returns the formatted string, or null when the value is absent
+ */
+export declare const formatUsdNullable: (value: number | null | undefined, locale?: string) => string | null;
+export declare const roundUsdToCents: (value: number) => number;

package/dist/cjs/routing/format.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.roundUsdToCents = exports.formatUsdNullable = exports.formatUsd = void 0;
+/**
+ * Formats a United States dollar number to a cent-precise string ("1,234.50",
+ * or "1.234,50" in German). No leading currency symbol — callers prepend it
+ * where the design needs one. The single source of truth shared by the raw
+ * producers (cent-rounding) and the display adapter (final formatting).
+ *
+ * `locale` defaults to `'en-US'` so every caller that does not read the
+ * reader's own language — the raw producers, and every existing test —
+ * keeps today's exact string. THE DISPLAY ADAPTER (`toRouteView.ts`) is the
+ * one caller that should pass the reader's own Lingui locale (`i18n.locale`):
+ * without it, the route strip's dollar figures stayed English-formatted
+ * inside every other translated screen, the one number on the page that
+ * never adopted the reader's language. The digit count never moves — only
+ * `toLocaleString`'s grouping and decimal separators do, per
+ * `minimumFractionDigits`/`maximumFractionDigits` staying pinned at 2.
+ *
+ * @param value - the United States dollar amount as a number
+ * @param locale - a BCP 47 locale tag to format with; defaults to `'en-US'`
+ * @returns the formatted two-decimal string, without a leading `$`
+ */
+const formatUsd = (value, locale = 'en-US') => value.toLocaleString(locale, { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+exports.formatUsd = formatUsd;
+/**
+ * Nullable {@link formatUsd}: null/undefined pass through as null so an unpriced
+ * value renders as absent rather than "0.00".
+ *
+ * @param value - the United States dollar amount, or null/undefined when unknown
+ * @param locale - a BCP 47 locale tag to format with; defaults to `'en-US'`
+ * @returns the formatted string, or null when the value is absent
+ */
+const formatUsdNullable = (value, locale) => value === null || value === undefined ? null : (0, exports.formatUsd)(value, locale);
+exports.formatUsdNullable = formatUsdNullable;
+/**
+ * Rounds a United States dollar amount to whole cents.
+ *
+ * This replaces cent-rounding that went through the DISPLAY formatter and parsed
+ * the result back — `Number(formatUsd(value).replace(/,/g, ''))`. That works
+ * only while the display is pinned to a locale which groups with commas and
+ * decimalises with a dot. The moment money follows the reader's language, a
+ * German build formats 1234.56 as "1.234,56", and stripping the commas from THAT
+ * yields 1.23456: a fee understated by a factor of a thousand, silently, with no
+ * NaN anywhere to make it visible.
+ *
+ * It keeps its OWN formatter rather than borrowing the display one, pinned to a
+ * fixed locale and with grouping switched off, so the string it parses has no
+ * separators to strip and no locale to disagree with. That also makes it exact
+ * rather than merely close: `Math.round(value * 100) / 100` looks equivalent and
+ * is not, because it rounds the binary double while the formatter rounds the
+ * decimal the reader typed — they disagree on 1.005, giving 1.00 against 1.01.
+ * Matching the old behaviour to the cent is the point, so the old engine stays.
+ *
+ * @param value - the United States dollar amount
+ * @returns the amount rounded to two decimal places
+ */
+const centRounder = new Intl.NumberFormat('en-US', {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+    useGrouping: false,
+});
+const roundUsdToCents = (value) => Number(centRounder.format(value));
+exports.roundUsdToCents = roundUsdToCents;