@gibs/bridge-sdk 1.12.0 → 1.13.1

package/dist/routing/search/score.js

@@ -0,0 +1,427 @@
+import { isNativeAsset } from '../../ecosystems.js';
+import { compareRoutePlansByDeliveredAmount, planIsRankable, isRankableBasis, } from './graph.js';
+/**
+ * PHASE 0 — FOUNDATION ONLY. Today this module holds exactly one function,
+ * {@link waitPenaltyPpm}, moved here unchanged from
+ * `packages/ui/src/lib/stores/consolidated-quote.ts` (that file now imports
+ * and re-exports it, so every existing caller keeps working). Phase 1's
+ * `score.ts` work (design section 4) generalizes `candidateNetValueUsd` and
+ * `netValueAfterWaitPenalty` from `../producers.js` and
+ * `packages/ui/src/lib/state/useRouteOptions.ts` into one `scoreRoutePlan`
+ * function that lives here beside it.
+ *
+ * WHY THIS MOVES TO `bridge-sdk` AT ALL. `waitPenaltyPpm` is a pure function
+ * of a number — it has no dependency on React, a store, or any
+ * user-interface concern — and `scoreRoutePlan` will need it to score a
+ * `RoutePlan` (`../graph.js`), which is a `bridge-sdk` type. Leaving the
+ * function in the user-interface package would make `bridge-sdk`'s own
+ * scoring logic import FROM the application that is supposed to consume it.
+ */
+/**
+ * The share of the transfer a full minute of extra waiting is charged, in
+ * parts per million — 5,000 ppm is half of one percent.
+ *
+ * WHERE THE NUMBER COMES FROM. The owner's own crossing: LI.FI (through
+ * squid) claimed twenty seconds and Relay claimed two, and the strip
+ * preferred LI.FI because it delivered 0.075% more — nine cents on a
+ * hundred and twenty-six dollars. The transfer was still unsettled
+ * twenty-five minutes later. A second live measurement on Base to Polygon:
+ * twenty-nine seconds against three, for 0.0545%. Both are the same shape —
+ * a few cents of advantage bought with a ten-fold increase in the wait —
+ * and under this rate both go the other way: at eighteen seconds of extra
+ * claimed wait a route must deliver 0.15% more to win, and at twenty-six
+ * seconds it must deliver 0.217% more. Neither does.
+ *
+ * The rate is also calibrated NOT to override a real price advantage. A
+ * route that is a full minute slower still wins on 0.6% more delivered,
+ * which on a hundred-and-twenty-six-dollar transfer is seventy-six cents —
+ * a figure worth waiting a minute for, where nine cents is not.
+ */
+const WAIT_PENALTY_PPM_PER_MINUTE = 5_000;
+/** The wait beyond which extra claimed seconds stop adding to the penalty. */
+const WAIT_PENALTY_CEILING_SECONDS = 60;
+/**
+ * What a quote's CLAIMED duration costs it in the ranking, as a share of the
+ * transfer in parts per million. It ramps linearly to
+ * {@link WAIT_PENALTY_PPM_PER_MINUTE} at {@link WAIT_PENALTY_CEILING_SECONDS}
+ * and stops there.
+ *
+ * THE DURATION IS A CLAIM AND IS TREATED AS ONE. The route that prompted
+ * this ran about seventy-five times its provider's own estimate, so the
+ * figure cannot be trusted as a measurement of anything. It is still the
+ * only signal there is, and it is informative in one direction: a provider
+ * that says it will take longer is not going to turn out faster, and a
+ * claimed wait understates the real one far more often than it overstates
+ * it. So the penalty is used to demand a real price advantage before ANY
+ * extra claimed wait is accepted — never to predict a settlement time, and
+ * never to produce a number shown to the reader. Nothing on screen is
+ * adjusted by this; only the order is.
+ *
+ * The ceiling is what keeps the rule from becoming a speed preference. Past
+ * a minute the penalty stops growing, so a route that is genuinely worth
+ * waiting for still wins on the strength of its price.
+ *
+ * @param durationSeconds - the provider's own claimed execution duration
+ * @returns the penalty as parts per million of the transfer, 0 for a missing claim
+ */
+export const waitPenaltyPpm = (durationSeconds) => {
+    if (typeof durationSeconds !== 'number' || !Number.isFinite(durationSeconds))
+        return 0;
+    if (durationSeconds <= 0)
+        return 0;
+    const rampedSeconds = Math.min(durationSeconds, WAIT_PENALTY_CEILING_SECONDS);
+    return Math.round((WAIT_PENALTY_PPM_PER_MINUTE * rampedSeconds) / WAIT_PENALTY_CEILING_SECONDS);
+};
+// ---------------------------------------------------------------------------
+// scoreRoutePlan — the one maximization function
+// ---------------------------------------------------------------------------
+/**
+ * The share of the transfer charged for EACH reader action beyond the first,
+ * in parts per million — see {@link signaturePenaltyUsd}.
+ *
+ * THIS IS A PROPOSAL, NOT A MEASUREMENT. Unlike {@link WAIT_PENALTY_PPM_PER_MINUTE},
+ * which is calibrated against two logged, live crossings, no comparable
+ * signature-count measurement exists yet. 2,500 ppm (0.25% of the delivered
+ * amount) is a starting point sized to sit BELOW the wait penalty's own
+ * ceiling (5,000 ppm) — a second signature should cost less than the worst
+ * wait penalty already accepted, since a signature is a moment of the
+ * reader's attention, not twenty-five minutes of theirs. The owner is meant
+ * to calibrate this against real reader behavior once it ships.
+ */
+export const SIGNATURE_PENALTY_PPM = 2_500;
+/**
+ * SUPERSEDED FOR THE SEARCH ENGINE'S OWN RANKING — see
+ * {@link compareRoutePlansByGasAdjustedDeliveredAmount}, below, which
+ * `waves.ts` now uses in place of {@link compareRoutePlansByScoreAdjustedDeliveredAmount}
+ * once real gas data exists. A flat parts-per-million guess cannot tell a
+ * cheap chain from an expensive one, and it charges nothing for gas at all —
+ * the owner's own instruction: "it's custom for each provider ... gather the
+ * logic around how much a user is about to be charged." This constant, and
+ * {@link GAS_TOPUP_PENALTY_PPM} below, are KEPT UNCHANGED because
+ * {@link scoreRoutePlan} and every existing United States dollar-based
+ * caller of it (`plan-route-data.ts`, `producers.ts`, the user interface's
+ * own single-candidate scoring) still read them — migrating those callers to
+ * a real gas-cost model is FLAGGED HERE as follow-up work outside this
+ * module's own owned scope, not done silently in this change.
+ */
+/**
+ * The minimum a signature is ever charged, in United States dollars — see
+ * {@link signaturePenaltyUsd}.
+ *
+ * THIS IS A PROPOSAL, NOT A MEASUREMENT. Without a floor, {@link SIGNATURE_PENALTY_PPM}
+ * charges almost nothing on a small transfer (0.25% of ten dollars is two and
+ * a half cents), which would let a route add a whole extra signature for a
+ * fraction of a cent. One dollar is a guess at what a reader's own time and
+ * attention for one extra wallet prompt is worth, floored so it cannot be
+ * bought away by a large delivered amount either — the floor and the rate are
+ * a `max`, so whichever is larger applies. The owner is meant to calibrate
+ * this once real reader behavior is observed.
+ */
+export const SIGNATURE_PENALTY_FLOOR_USD = 1;
+/**
+ * The share of the transfer charged for EACH intermediate chain where the
+ * reader holds no gas, in parts per million — see {@link gasTopUpPenaltyUsd}.
+ *
+ * THIS IS A PROPOSAL, NOT A MEASUREMENT. Sized larger than
+ * {@link SIGNATURE_PENALTY_PPM} because a gas top-up is not a moment of
+ * attention like a signature — it is a SEPARATE errand: acquire the
+ * intermediate chain's native coin, by another bridge or a purchase, before
+ * the planned hop can even be signed. That errand risks stranding the
+ * transfer mid-route if the reader does not complete it, which the
+ * "stranded funds" risk in the route-search design's section 10 names
+ * directly. The owner is meant to calibrate this once real reader behavior
+ * is observed.
+ */
+export const GAS_TOPUP_PENALTY_PPM = 10_000;
+/**
+ * The minimum a gas top-up is ever charged, in United States dollars — see
+ * {@link gasTopUpPenaltyUsd}.
+ *
+ * THIS IS A PROPOSAL, NOT A MEASUREMENT. Set higher than
+ * {@link SIGNATURE_PENALTY_FLOOR_USD} for the same reason
+ * {@link GAS_TOPUP_PENALTY_PPM} is: this penalty stands in for a separate
+ * errand with its own real cost (buying gas on a chain the reader was not
+ * already using), not a moment of attention. The owner is meant to calibrate
+ * this once real reader behavior is observed.
+ */
+export const GAS_TOPUP_PENALTY_FLOOR_USD = 3;
+/**
+ * What one extra reader action (a signature or a pay-by-hand deposit) costs
+ * in the ranking, in United States dollars: the larger of
+ * {@link SIGNATURE_PENALTY_FLOOR_USD} and {@link SIGNATURE_PENALTY_PPM} of
+ * the delivered amount. See both constants' docs for where the numbers come
+ * from and that they are proposals, not measurements.
+ *
+ * @param deliveredUsd - the route's delivered value in United States dollars
+ * @returns the penalty for one extra action, always positive
+ */
+const signaturePenaltyUsd = (deliveredUsd) => Math.max(SIGNATURE_PENALTY_FLOOR_USD, (deliveredUsd * SIGNATURE_PENALTY_PPM) / 1_000_000);
+/**
+ * What one intermediate chain with no reader gas costs in the ranking, in
+ * United States dollars: the larger of {@link GAS_TOPUP_PENALTY_FLOOR_USD}
+ * and {@link GAS_TOPUP_PENALTY_PPM} of the delivered amount. See both
+ * constants' docs for where the numbers come from and that they are
+ * proposals, not measurements.
+ *
+ * @param deliveredUsd - the route's delivered value in United States dollars
+ * @returns the penalty for one gasless intermediate chain, always positive
+ */
+const gasTopUpPenaltyUsd = (deliveredUsd) => Math.max(GAS_TOPUP_PENALTY_FLOOR_USD, (deliveredUsd * GAS_TOPUP_PENALTY_PPM) / 1_000_000);
+/**
+ * The one maximization function a route search ranks every plan by —
+ * generalizing today's `candidateNetValueUsd` and `netValueAfterWaitPenalty`
+ * (`../producers.js` and `packages/ui/src/lib/state/useRouteOptions.ts`)
+ * from a single quoted candidate to a whole {@link RouteScoreInputs} plan, per
+ * the route-search design's section 4:
+ *
+ * ```
+ * score = D − P − F
+ *         − Σ_legs D·waitPenaltyPpm(claimedSeconds_leg)/1e6
+ *         − (A − 1)·max($1, D·SIGNATURE_PENALTY_PPM/1e6)
+ *         − G·max($3, D·GAS_TOPUP_PENALTY_PPM/1e6)
+ * ```
+ *
+ * A HIGHER SCORE IS BETTER. A route search picks the plan with the largest
+ * `scoreRoutePlan` result, exactly as today's ranking picks the candidate
+ * with the largest `netValueAfterWaitPenalty`.
+ *
+ * THE WAIT PENALTY IS UNCHANGED, JUST SUMMED ACROSS LEGS. Today's single-quote
+ * penalty is `deliveredUsd * waitPenaltyPpm(oneClaimedDuration) / 1e6`, one
+ * term. A plan can carry several hops, each with its own claimed duration, so
+ * this sums that same per-unit charge over every hop in
+ * {@link RouteScoreInputs.legClaimedDurationsSeconds} — still against the
+ * PLAN'S total delivered value, not each leg's own, because the reader is
+ * charged for the whole route's wait, not a fraction of it per leg.
+ *
+ * WHAT IS NEW: THE ACTION AND GAS-TOP-UP TERMS. Today's ranking only ever
+ * compared plans that cost one signature, so it had nothing to charge for a
+ * second one. A general search can find a plan needing two or three actions,
+ * or one that strands the reader without gas on an intermediate chain — see
+ * `signaturePenaltyUsd` and `gasTopUpPenaltyUsd` for what each extra action
+ * or gasless chain costs, and {@link SIGNATURE_PENALTY_PPM} /
+ * {@link GAS_TOPUP_PENALTY_PPM} for where the rates come from.
+ *
+ * WHY `(A − 1)` AND NOT `A`. Every plan needs at least one action to execute
+ * at all — signing or depositing is not itself a mark against a route, it is
+ * what EXECUTES it. Only actions beyond the first are extra friction the
+ * reader would not have paid on a one-action alternative, so only those are
+ * charged.
+ *
+ * REFUSES AN UNPRICED PLAN BY SCORING IT NEGATIVE INFINITY — PHASE 3. When
+ * {@link RouteScoreInputs.basis} is `'unpriced'`, `deliveredUsd` is a bare
+ * decimal rescale with no value behind it (see `EstimateBasis`'s own doc,
+ * `graph.ts`), and no arithmetic performed on it below would make it
+ * trustworthy. Returning `Number.NEGATIVE_INFINITY` rather than, say, `-1` or
+ * `0` is what makes this impossible to sidestep BY ACCIDENT: an ordinary `>`
+ * comparison, a plain numeric `.sort()`, or a `Math.max` over several plans'
+ * scores all already put an unpriced plan last WITHOUT the caller having to
+ * remember to check {@link RouteScoreInputs.basis} first — the same defence
+ * `compareRoutePlansByDeliveredAmount` (`graph.ts`) applies explicitly to a
+ * plan-to-plan comparison, applied here so a caller who reaches for
+ * `scoreRoutePlan` directly, for a single plan's score, gets the same
+ * protection for free.
+ *
+ * @param inputs - the plan's already-priced figures; see {@link RouteScoreInputs}
+ * @returns the plan's score — higher is better, and the units are United
+ *   States dollars throughout; `Number.NEGATIVE_INFINITY` for an unpriced plan
+ */
+// ---------------------------------------------------------------------------
+// compareRoutePlansByScoreAdjustedDeliveredAmount — ranking that charges for
+// an extra signature, without needing a United States dollar price
+// ---------------------------------------------------------------------------
+/** `SIGNATURE_PENALTY_PPM`'s denominator: parts per million, as a bigint. */
+const PPM_DENOMINATOR = 1000000n;
+/**
+ * `plan`'s last-hop `deliveredAmount`, discounted by {@link SIGNATURE_PENALTY_PPM}
+ * for every signature beyond the first — proportionally, in the delivered
+ * token's own base units, entirely in bigint arithmetic.
+ *
+ * WHY ONLY THE PROPORTIONAL SHARE, NEVER {@link SIGNATURE_PENALTY_FLOOR_USD}.
+ * The floor is denominated in United States dollars; converting a base-unit
+ * `deliveredAmount` into dollars needs a live price, which a `RoutePlan`
+ * (`graph.ts`) does not carry — it is a bigint amount in one token's own
+ * units, nothing more. `scoreRoutePlan` still applies the full formula,
+ * floor included, once a caller (`plan-route-data.ts`) has priced a plan into
+ * `RouteScoreInputs`. This function is the version usable at the STRUCTURAL
+ * ranking sites — `enumerate.ts`'s cut and `waves.ts`'s between-wave
+ * re-ranking — which only ever see the plan's own hops, not a price. See
+ * {@link compareRoutePlansByScoreAdjustedDeliveredAmount}'s own doc for why a
+ * proportional-only penalty is still enough to settle the case it exists for.
+ *
+ * @param plan - the plan to discount
+ * @returns the discounted delivered amount, floored at zero
+ */
+const signaturePenaltyAdjustedDeliveredAmount = (plan) => {
+    const deliveredAmount = plan.hops[plan.hops.length - 1]?.outcome.deliveredAmount ?? 0n;
+    const extraActionCount = Math.max(0, plan.signatures.length - 1);
+    const penaltyPpm = BigInt(extraActionCount) * BigInt(SIGNATURE_PENALTY_PPM);
+    const retainedPpm = penaltyPpm >= PPM_DENOMINATOR ? 0n : PPM_DENOMINATOR - penaltyPpm;
+    return (deliveredAmount * retainedPpm) / PPM_DENOMINATOR;
+};
+/**
+ * Orders two RANKABLE plans (both pass `graph.ts`'s `planIsRankable`) by
+ * their {@link signaturePenaltyAdjustedDeliveredAmount} rather than their raw
+ * `deliveredAmount` — the STRUCTURAL counterpart to `graph.ts`'s
+ * {@link @gibs/bridge-sdk/routing/search/graph!compareRoutePlansByDeliveredAmount},
+ * reusing every one of that function's rules (rankable beats unrankable,
+ * `compareUnrankablePlans`'s tiebreak among two unrankable plans) and adding
+ * exactly one more: within two RANKABLE plans, a plan needing more
+ * signatures than another must clear {@link SIGNATURE_PENALTY_PPM} of
+ * "extra" delivered value per extra signature before it is allowed to win,
+ * not merely `> 0`.
+ *
+ * THE DEFECT THIS CLOSES. `SIGNATURE_PENALTY_PPM` and `GAS_TOPUP_PENALTY_PPM`
+ * existed in this module as constants `scoreRoutePlan` charges — but nothing
+ * in the actual ranking path called `scoreRoutePlan` at all:
+ * `enumerate.ts`'s cut, `waves.ts`'s between-wave re-ranking, and
+ * `useRouteSearch.ts`'s final sort all imported `graph.ts`'s plain
+ * delivered-amount comparator directly, so a route needing a second
+ * signature for a fractional gain (measured: 0.006% more, needing one more
+ * wallet prompt) always won outright. Sorting on
+ * {@link signaturePenaltyAdjustedDeliveredAmount} instead is what makes that
+ * lose to the one-signature alternative: the extra signature's proportional
+ * cost (0.25% per {@link SIGNATURE_PENALTY_PPM}) outweighs a 0.006% edge by
+ * roughly forty times.
+ *
+ * WHY NOT `GAS_TOPUP_PENALTY_PPM` HERE TOO. A gasless-intermediate-chain
+ * charge needs to know whether the connected account holds gas on a chain in
+ * the middle of the plan — a live wallet balance read `RoutePlan` has no way
+ * to name. Applying it here would require guessing, which this comparator
+ * refuses to do; `GAS_TOPUP_PENALTY_PPM` is still applied wherever a caller
+ * has that balance and reaches for `scoreRoutePlan` directly (`plan-route-data.ts`
+ * onward). Left as an OWNER DECISION whether a structural ranking site should
+ * ever get gas-balance context of its own.
+ *
+ * @param a - one plan being compared
+ * @param b - the other
+ * @returns negative when `a` ranks ahead of `b`, positive when `b` ranks
+ *   ahead of `a`, zero when they tie
+ */
+export const compareRoutePlansByScoreAdjustedDeliveredAmount = (a, b) => {
+    const rankableA = planIsRankable(a.hops);
+    const rankableB = planIsRankable(b.hops);
+    if (rankableA !== rankableB)
+        return rankableA ? -1 : 1;
+    if (!rankableA)
+        return compareRoutePlansByDeliveredAmount(a, b);
+    const adjustedA = signaturePenaltyAdjustedDeliveredAmount(a);
+    const adjustedB = signaturePenaltyAdjustedDeliveredAmount(b);
+    if (adjustedA === adjustedB)
+        return 0;
+    return adjustedA > adjustedB ? -1 : 1;
+};
+export const scoreRoutePlan = (inputs) => {
+    if (!isRankableBasis(inputs.basis)) {
+        return Number.NEGATIVE_INFINITY;
+    }
+    const totalWaitPenaltyUsd = inputs.legClaimedDurationsSeconds.reduce((total, claimedSeconds) => total + (inputs.deliveredUsd * waitPenaltyPpm(claimedSeconds)) / 1_000_000, 0);
+    const extraActionCount = Math.max(0, inputs.readerActionCount - 1);
+    const totalSignaturePenaltyUsd = extraActionCount * signaturePenaltyUsd(inputs.deliveredUsd);
+    const totalGasTopUpPenaltyUsd = inputs.gaslessIntermediateChainCount * gasTopUpPenaltyUsd(inputs.deliveredUsd);
+    return (inputs.deliveredUsd -
+        inputs.paidUsd -
+        inputs.outsideFeesUsd -
+        totalWaitPenaltyUsd -
+        totalSignaturePenaltyUsd -
+        totalGasTopUpPenaltyUsd);
+};
+/**
+ * A PLACEHOLDER {@link GasCostFor} that charges nothing — preserves the
+ * behaviour of ranking on raw delivered amount for a caller that has not yet
+ * wired a real gas-price and native-price source. NOT A PRODUCTION DEFAULT:
+ * unlike {@link WAIT_PENALTY_PPM_PER_MINUTE}'s two logged, live crossings, no
+ * per-chain gas figure here would be a measurement — it would be a guess
+ * dressed up as one, exactly what Rule 13 of this codebase's own working
+ * principles warns against. A host should always supply its own
+ * {@link GasCostFor} once it has gas-price and native-price feeds to build
+ * one from; this export exists only so `waves.ts`'s own default comparator
+ * has something total to call when nobody has.
+ */
+export const zeroGasCostFor = () => ({ gasAmount: 0n, refuelAmount: 0n });
+/**
+ * Whether the section at `sectionIndex` starts with native coin already in
+ * the reader's hand: the hop that ends the PREVIOUS section delivers the
+ * chain's native coin, so the reader arrives holding gas for this section's
+ * own signature and needs no top-up there, whatever their balance was.
+ *
+ * Always false for the first section — nothing lands before it, so its gas
+ * can only come from the reader's own balance.
+ *
+ * @param plan - the plan the section belongs to
+ * @param sectionIndex - 0-based index into `plan.signatures`
+ * @returns true when the previous section lands native coin on this
+ *   section's chain
+ */
+export const sectionIsFundedByLanding = (plan, sectionIndex) => {
+    if (sectionIndex < 1)
+        return false;
+    const previousGroup = plan.signatures[sectionIndex - 1];
+    const landingHop = plan.hops[previousGroup?.[previousGroup.length - 1] ?? -1];
+    if (landingHop === undefined)
+        return false;
+    return isNativeAsset(landingHop.edge.to.address, landingHop.edge.to.ecosystem);
+};
+/**
+ * `plan`'s last-hop `deliveredAmount`, minus the REAL cost of every
+ * signature it needs — `gasCostFor` charged ONCE per signature group
+ * (`plan.signatures`, built by `groupHopsBySignature`), on the chain and
+ * carrier of that group's FIRST hop, which is the hop the reader actually
+ * signs (or deposits by hand) for that group. A group's refuel cost is
+ * dropped when the previous group lands native coin
+ * ({@link sectionIsFundedByLanding}). Floored at zero: a plan whose
+ * gas costs exceed its own delivered amount is worth nothing, never negative.
+ *
+ * @param plan - the plan to charge
+ * @param gasCostFor - supplies each signature's real cost; see {@link GasCostFor}
+ * @returns the gas-adjusted delivered amount, in the plan's destination token's base units
+ */
+export const gasAdjustedDeliveredAmount = (plan, gasCostFor) => {
+    const deliveredAmount = plan.hops[plan.hops.length - 1]?.outcome.deliveredAmount ?? 0n;
+    const totalGasCost = plan.signatures.reduce((total, group, sectionIndex) => {
+        const firstHopIndex = group[0];
+        const firstHop = firstHopIndex === undefined ? undefined : plan.hops[firstHopIndex];
+        if (firstHop === undefined)
+            return total;
+        const quote = gasCostFor(firstHop.edge.from.chainId, firstHop.edge.carrier);
+        const refuelAmount = sectionIsFundedByLanding(plan, sectionIndex) ? 0n : quote.refuelAmount;
+        return total + quote.gasAmount + refuelAmount;
+    }, 0n);
+    const netAmount = deliveredAmount - totalGasCost;
+    return netAmount < 0n ? 0n : netAmount;
+};
+/**
+ * Orders two plans by {@link gasAdjustedDeliveredAmount} rather than raw
+ * `deliveredAmount` or {@link signaturePenaltyAdjustedDeliveredAmount}'s flat
+ * ppm guess — the structural ranking `waves.ts` uses once Round A/B have real
+ * gas data to charge, replacing {@link SIGNATURE_PENALTY_PPM}/
+ * {@link GAS_TOPUP_PENALTY_PPM} at that one site per the owner's own
+ * instruction (see both constants' updated docs). A CURRIED FACTORY, not a
+ * plain comparator, because the real cost this needs — {@link GasCostFor} —
+ * is caller-supplied and cannot be a module-level default the way
+ * {@link compareRoutePlansByScoreAdjustedDeliveredAmount} is; call it once
+ * per search with the caller's own `gasCostFor`, then pass the returned
+ * comparator wherever a plan-to-plan comparison is needed.
+ *
+ * KEEPS THE SAME RANKABLE-BEFORE-UNRANKABLE RULE `compareRoutePlansByScoreAdjustedDeliveredAmount`
+ * ALREADY APPLIES, unchanged, including its `compareRoutePlansByDeliveredAmount`
+ * tiebreak among two unrankable plans — only the tiebreak among two RANKABLE
+ * plans changes, from a proportional signature-count discount to the route's
+ * own real charges.
+ *
+ * @param gasCostFor - supplies each signature's real cost; see {@link GasCostFor}
+ * @returns a comparator: negative when `a` ranks ahead of `b`, positive when
+ *   `b` ranks ahead of `a`, zero when they tie
+ */
+export const compareRoutePlansByGasAdjustedDeliveredAmount = (gasCostFor) => (a, b) => {
+    const rankableA = planIsRankable(a.hops);
+    const rankableB = planIsRankable(b.hops);
+    if (rankableA !== rankableB)
+        return rankableA ? -1 : 1;
+    if (!rankableA)
+        return compareRoutePlansByDeliveredAmount(a, b);
+    const adjustedA = gasAdjustedDeliveredAmount(a, gasCostFor);
+    const adjustedB = gasAdjustedDeliveredAmount(b, gasCostFor);
+    if (adjustedA === adjustedB)
+        return 0;
+    return adjustedA > adjustedB ? -1 : 1;
+};

package/dist/routing/usd-value.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The United States dollar value of a base-unit token amount at a given price, as
+ * a NUMBER — the numeric core of the user interface's `formatFiatValue` without the
+ * currency string. Returns null when the token is unpriced (`price` is null) or the
+ * computed value is not finite, mirroring the "return null for invalid state"
+ * convention so callers can fall back.
+ *
+ * @param params.balance - the amount in base units
+ * @param params.decimals - the token's decimals
+ * @param params.price - the token's United States dollar price, or null when unpriced
+ * @returns the dollar value as a number, or null
+ */
+export declare const usdValueOfAmount: (params: {
+    balance: bigint;
+    decimals: number;
+    price: number | null;
+}) => number | null;

package/dist/routing/usd-value.js

@@ -0,0 +1,25 @@
+import { formatUnits } from 'viem';
+/**
+ * The United States dollar value of a base-unit token amount at a given price, as
+ * a NUMBER — the numeric core of the user interface's `formatFiatValue` without the
+ * currency string. Returns null when the token is unpriced (`price` is null) or the
+ * computed value is not finite, mirroring the "return null for invalid state"
+ * convention so callers can fall back.
+ *
+ * @param params.balance - the amount in base units
+ * @param params.decimals - the token's decimals
+ * @param params.price - the token's United States dollar price, or null when unpriced
+ * @returns the dollar value as a number, or null
+ */
+export const usdValueOfAmount = (params) => {
+    const { balance, decimals, price } = params;
+    if (price === null)
+        return null;
+    const whole = Number(formatUnits(balance, decimals));
+    if (!Number.isFinite(whole))
+        return null;
+    const value = whole * price;
+    if (!Number.isFinite(value))
+        return null;
+    return value;
+};