@gibs/bridge-sdk 1.13.1 → 1.18.0

package/dist/cjs/routing/search/score.js

@@ -0,0 +1,445 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareRoutePlansByGasAdjustedDeliveredAmount = exports.gasAdjustedDeliveredAmount = exports.sectionIsFundedByLanding = exports.zeroGasCostFor = exports.scoreRoutePlan = exports.compareRoutePlansByScoreAdjustedDeliveredAmount = exports.GAS_TOPUP_PENALTY_FLOOR_USD = exports.GAS_TOPUP_PENALTY_PPM = exports.SIGNATURE_PENALTY_FLOOR_USD = exports.SIGNATURE_PENALTY_PPM = exports.waitPenaltyPpm = void 0;
+const ecosystems_js_1 = require("../../ecosystems.js");
+const graph_js_1 = require("./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
+ */
+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);
+};
+exports.waitPenaltyPpm = waitPenaltyPpm;
+// ---------------------------------------------------------------------------
+// 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.
+ */
+exports.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.
+ */
+exports.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.
+ */
+exports.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.
+ */
+exports.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(exports.SIGNATURE_PENALTY_FLOOR_USD, (deliveredUsd * exports.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(exports.GAS_TOPUP_PENALTY_FLOOR_USD, (deliveredUsd * exports.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(exports.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
+ */
+const compareRoutePlansByScoreAdjustedDeliveredAmount = (a, b) => {
+    const rankableA = (0, graph_js_1.planIsRankable)(a.hops);
+    const rankableB = (0, graph_js_1.planIsRankable)(b.hops);
+    if (rankableA !== rankableB)
+        return rankableA ? -1 : 1;
+    if (!rankableA)
+        return (0, graph_js_1.compareRoutePlansByDeliveredAmount)(a, b);
+    const adjustedA = signaturePenaltyAdjustedDeliveredAmount(a);
+    const adjustedB = signaturePenaltyAdjustedDeliveredAmount(b);
+    if (adjustedA === adjustedB)
+        return 0;
+    return adjustedA > adjustedB ? -1 : 1;
+};
+exports.compareRoutePlansByScoreAdjustedDeliveredAmount = compareRoutePlansByScoreAdjustedDeliveredAmount;
+const scoreRoutePlan = (inputs) => {
+    if (!(0, graph_js_1.isRankableBasis)(inputs.basis)) {
+        return Number.NEGATIVE_INFINITY;
+    }
+    const totalWaitPenaltyUsd = inputs.legClaimedDurationsSeconds.reduce((total, claimedSeconds) => total + (inputs.deliveredUsd * (0, exports.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);
+};
+exports.scoreRoutePlan = scoreRoutePlan;
+/**
+ * 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.
+ */
+const zeroGasCostFor = () => ({ gasAmount: 0n, refuelAmount: 0n });
+exports.zeroGasCostFor = zeroGasCostFor;
+/**
+ * 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
+ */
+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 (0, ecosystems_js_1.isNativeAsset)(landingHop.edge.to.address, landingHop.edge.to.ecosystem);
+};
+exports.sectionIsFundedByLanding = sectionIsFundedByLanding;
+/**
+ * `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
+ */
+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 = (0, exports.sectionIsFundedByLanding)(plan, sectionIndex) ? 0n : quote.refuelAmount;
+        return total + quote.gasAmount + refuelAmount;
+    }, 0n);
+    const netAmount = deliveredAmount - totalGasCost;
+    return netAmount < 0n ? 0n : netAmount;
+};
+exports.gasAdjustedDeliveredAmount = gasAdjustedDeliveredAmount;
+/**
+ * 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}
+ * TIE-BREAK: when the gas-adjusted amounts are equal, the plan with fewer
+ * signatures ranks first.
+ *
+ * @returns a comparator: negative when `a` ranks ahead of `b`, positive when
+ *   `b` ranks ahead of `a`, zero when they tie
+ */
+const compareRoutePlansByGasAdjustedDeliveredAmount = (gasCostFor) => (a, b) => {
+    const rankableA = (0, graph_js_1.planIsRankable)(a.hops);
+    const rankableB = (0, graph_js_1.planIsRankable)(b.hops);
+    if (rankableA !== rankableB)
+        return rankableA ? -1 : 1;
+    if (!rankableA)
+        return (0, graph_js_1.compareRoutePlansByDeliveredAmount)(a, b);
+    const adjustedA = (0, exports.gasAdjustedDeliveredAmount)(a, gasCostFor);
+    const adjustedB = (0, exports.gasAdjustedDeliveredAmount)(b, gasCostFor);
+    if (adjustedA !== adjustedB)
+        return adjustedA > adjustedB ? -1 : 1;
+    // EQUAL FIGURES: FEWER SIGNATURES RANKS FIRST. Two plans that deliver the
+    // same amount cost the reader different effort — each signature is one more
+    // wallet prompt. Without this the stable sort kept the depth-first walk
+    // order, so a three-signature plan could be selected over a two-signature
+    // plan showing the same figure.
+    return a.signatures.length - b.signatures.length;
+};
+exports.compareRoutePlansByGasAdjustedDeliveredAmount = compareRoutePlansByGasAdjustedDeliveredAmount;

package/dist/cjs/routing/swap-transactions.d.ts

@@ -0,0 +1,95 @@
+import { type Hex } from 'viem';
+import { type SignedLeg } from '../settings.js';
+import type { SwapVenues } from '../swap-venues.js';
+import type { HopEdge, PlannedHop } from './search/graph.js';
+/**
+ * The same-chain, one-signature transaction shape every sender in this file
+ * builds: a target contract, a native-coin value, and encoded calldata.
+ */
+export type SwapCallInputs = {
+    readonly to: Hex;
+    readonly value: bigint;
+    readonly data: Hex;
+};
+/**
+ * Builds a same-chain PulseX swap transaction for one planned route-search
+ * hop. The interface's section signing (`packages/ui` `state/sectionSigning.ts`)
+ * and the SDK's execution planner (`execution.ts`) both call it, so there is
+ * exactly one place that turns "swap this hop" into calldata.
+ *
+ * SIGNS THE PATH THE HOP WAS PRICED ON. The PulseX carrier picks the best of
+ * many paths through its hub tokens and records the winner on the hop's
+ * outcome; `pulseXSwapPathForHop` (`carriers/pulsex.ts`) reads it back
+ * and checks it fits the hop's edge. This never rebuilds a path: a rebuilt
+ * path is a quote on one route and a signature on another. A hop that
+ * records no path is refused. REUSES `pulseXSwapTransactionInputs` (`settings.ts`)
+ * for the encoding, never re-implements it: that function already carries the
+ * `swapRefusal` guard (refuses to build a call for a leg the screen is not
+ * looking at) and the native-in/native-out/token-token branching.
+ *
+ * SIGNS ON THE EDGE'S OWN ROUTER. A PulseX edge names the deployment it was
+ * quoted on (`venueForEdge`: V1 or V2, each with its own pools). The
+ * caller's `routerAddress` must be that same router — it is also the router
+ * the caller approved to spend the input token — or nothing is built. A V2
+ * quote signed on V1 would trade against a different pool than the one the
+ * reader was shown.
+ *
+ * @param options - the hop to swap, the amount and slippage-adjusted
+ *   minimum, who receives the output, the signing deadline, what the caller
+ *   believes this signature does (`signedLeg`), the chain it executes on, the
+ *   resolved router address, and the swap venues the router must belong to
+ *   (the defaults when omitted)
+ * @returns the swap transaction inputs, or null when the hop records no
+ *   PulseX swap path, names no known router, `routerAddress` is not the
+ *   edge's own router, the leg on screen disagrees, or any of
+ *   `pulseXSwapTransactionInputs`'s own preconditions are unmet
+ */
+export declare const buildPulseXSwapTransaction: (options: {
+    readonly hop: Pick<PlannedHop, "edge" | "outcome">;
+    readonly amountIn: bigint;
+    readonly minAmountOut: bigint;
+    readonly recipient: Hex | null;
+    readonly deadline: bigint;
+    readonly signedLeg: SignedLeg | null;
+    readonly chainId: number | null;
+    readonly routerAddress: Hex | null;
+    /** The venues the edge's router must belong to. Omitted means the defaults. */
+    readonly venues?: SwapVenues;
+}) => SwapCallInputs | null;
+/**
+ * Builds a native-coin wrap/unwrap transaction for one route-search graph
+ * edge — PLS<->WPLS on PulseChain, ETH<->WETH on Ethereum, or the same pair
+ * on any other chain `config.ts`'s `nativeAssetOut` names one for.
+ *
+ * A WRAP IS NOT A SWAP CALL. There is no PulseX pool for native-versus-wrapped
+ * — see `routing/carriers/wrap.ts`'s own doc — so this never touches the
+ * PulseX router: wrapping sends `amountIn` native coin to the wrapped token's
+ * own `deposit()`; unwrapping calls `withdraw(amountIn)` on it with zero
+ * value. The `edge` names which direction: its `from`/`to` addresses are
+ * checked against the zero-address sentinel, never assumed from a caller
+ * flag, so a swapped/malformed edge is refused rather than guessed at.
+ *
+ * @param options - the edge to wrap or unwrap, and the amount in the SOURCE
+ *   token's base units (native units wrapping, wrapped units unwrapping —
+ *   native and wrapped share decimals on every chain this carrier covers)
+ * @returns the wrap/unwrap transaction inputs, or null when `amountIn` is not
+ *   positive or the edge is not exactly one native/wrapped pair
+ */
+export declare const buildWrapTransaction: (options: {
+    readonly edge: HopEdge;
+    readonly amountIn: bigint;
+}) => SwapCallInputs | null;
+/**
+ * The slippage floor a swap signs: the quoted output less the slippage
+ * allowance, rounded down. The interface's engine signing and the SDK's
+ * execution planner both read it, so the two never sign different floors for
+ * the same quote.
+ *
+ * @param options.quotedAmount - the hop's quoted output, in the output token's base units
+ * @param options.slippageBasisPoints - the allowance, in basis points (100 is 1%)
+ * @returns the minimum output the swap accepts
+ */
+export declare const swapMinimumOut: ({ quotedAmount, slippageBasisPoints, }: {
+    readonly quotedAmount: bigint;
+    readonly slippageBasisPoints: bigint;
+}) => bigint;

package/dist/cjs/routing/swap-transactions.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.swapMinimumOut = exports.buildWrapTransaction = exports.buildPulseXSwapTransaction = void 0;
+const viem_1 = require("viem");
+const settings_js_1 = require("../settings.js");
+const config_js_1 = require("../config.js");
+const pulsex_js_1 = require("./carriers/pulsex.js");
+/**
+ * The minimal WETH9-style wrap/unwrap interface: `deposit()` mints the
+ * wrapped token for the native coin sent with the call, `withdraw(uint256)`
+ * burns wrapped balance and returns native coin. Every wrapped-native
+ * contract this application bridges to exposes exactly this pair — see
+ * `carriers/wrap.ts`, whose own doc records the selectors as confirmed
+ * present on WPLS by bytecode inspection (2026-09-24). Kept local rather than
+ * added to `@gibs/abis`: the interface is two standard, unchanging selectors
+ * rather than a contract-specific ABI.
+ */
+const wrapAbi = (0, viem_1.parseAbi)(['function deposit() payable', 'function withdraw(uint256 amount)']);
+/**
+ * Builds a same-chain PulseX swap transaction for one planned route-search
+ * hop. The interface's section signing (`packages/ui` `state/sectionSigning.ts`)
+ * and the SDK's execution planner (`execution.ts`) both call it, so there is
+ * exactly one place that turns "swap this hop" into calldata.
+ *
+ * SIGNS THE PATH THE HOP WAS PRICED ON. The PulseX carrier picks the best of
+ * many paths through its hub tokens and records the winner on the hop's
+ * outcome; `pulseXSwapPathForHop` (`carriers/pulsex.ts`) reads it back
+ * and checks it fits the hop's edge. This never rebuilds a path: a rebuilt
+ * path is a quote on one route and a signature on another. A hop that
+ * records no path is refused. REUSES `pulseXSwapTransactionInputs` (`settings.ts`)
+ * for the encoding, never re-implements it: that function already carries the
+ * `swapRefusal` guard (refuses to build a call for a leg the screen is not
+ * looking at) and the native-in/native-out/token-token branching.
+ *
+ * SIGNS ON THE EDGE'S OWN ROUTER. A PulseX edge names the deployment it was
+ * quoted on (`venueForEdge`: V1 or V2, each with its own pools). The
+ * caller's `routerAddress` must be that same router — it is also the router
+ * the caller approved to spend the input token — or nothing is built. A V2
+ * quote signed on V1 would trade against a different pool than the one the
+ * reader was shown.
+ *
+ * @param options - the hop to swap, the amount and slippage-adjusted
+ *   minimum, who receives the output, the signing deadline, what the caller
+ *   believes this signature does (`signedLeg`), the chain it executes on, the
+ *   resolved router address, and the swap venues the router must belong to
+ *   (the defaults when omitted)
+ * @returns the swap transaction inputs, or null when the hop records no
+ *   PulseX swap path, names no known router, `routerAddress` is not the
+ *   edge's own router, the leg on screen disagrees, or any of
+ *   `pulseXSwapTransactionInputs`'s own preconditions are unmet
+ */
+const buildPulseXSwapTransaction = (options) => {
+    const { hop, amountIn, minAmountOut, recipient, deadline, signedLeg, chainId, routerAddress } = options;
+    const { edge } = hop;
+    const swapPath = (0, pulsex_js_1.pulseXSwapPathForHop)(hop);
+    if (swapPath === null) {
+        return null;
+    }
+    const quotedRouter = (0, pulsex_js_1.venueForEdge)(options.venues ?? config_js_1.defaultSwapVenues, edge)?.router ?? null;
+    if (quotedRouter === null || routerAddress === null || !(0, viem_1.isAddressEqual)(quotedRouter, routerAddress)) {
+        return null;
+    }
+    return (0, settings_js_1.pulseXSwapTransactionInputs)({
+        signedLeg,
+        chainId,
+        routerAddress,
+        fromTokenAddress: edge.from.address,
+        toTokenAddress: edge.to.address,
+        swapPath,
+        amountIn,
+        minAmountOut,
+        recipient,
+        deadline,
+    });
+};
+exports.buildPulseXSwapTransaction = buildPulseXSwapTransaction;
+/**
+ * Builds a native-coin wrap/unwrap transaction for one route-search graph
+ * edge — PLS<->WPLS on PulseChain, ETH<->WETH on Ethereum, or the same pair
+ * on any other chain `config.ts`'s `nativeAssetOut` names one for.
+ *
+ * A WRAP IS NOT A SWAP CALL. There is no PulseX pool for native-versus-wrapped
+ * — see `routing/carriers/wrap.ts`'s own doc — so this never touches the
+ * PulseX router: wrapping sends `amountIn` native coin to the wrapped token's
+ * own `deposit()`; unwrapping calls `withdraw(amountIn)` on it with zero
+ * value. The `edge` names which direction: its `from`/`to` addresses are
+ * checked against the zero-address sentinel, never assumed from a caller
+ * flag, so a swapped/malformed edge is refused rather than guessed at.
+ *
+ * @param options - the edge to wrap or unwrap, and the amount in the SOURCE
+ *   token's base units (native units wrapping, wrapped units unwrapping —
+ *   native and wrapped share decimals on every chain this carrier covers)
+ * @returns the wrap/unwrap transaction inputs, or null when `amountIn` is not
+ *   positive or the edge is not exactly one native/wrapped pair
+ */
+const buildWrapTransaction = (options) => {
+    const { edge, amountIn } = options;
+    if (amountIn <= 0n) {
+        return null;
+    }
+    const fromIsNative = edge.from.address.toLowerCase() === viem_1.zeroAddress;
+    const toIsNative = edge.to.address.toLowerCase() === viem_1.zeroAddress;
+    // Exactly one side must be the native sentinel — a token/token pair, or a
+    // native/native no-op, is not a wrap edge at all.
+    if (fromIsNative === toIsNative) {
+        return null;
+    }
+    if (fromIsNative) {
+        return {
+            to: edge.to.address,
+            value: amountIn,
+            data: (0, viem_1.encodeFunctionData)({ abi: wrapAbi, functionName: 'deposit', args: [] }),
+        };
+    }
+    return {
+        to: edge.from.address,
+        value: 0n,
+        data: (0, viem_1.encodeFunctionData)({ abi: wrapAbi, functionName: 'withdraw', args: [amountIn] }),
+    };
+};
+exports.buildWrapTransaction = buildWrapTransaction;
+/**
+ * The slippage floor a swap signs: the quoted output less the slippage
+ * allowance, rounded down. The interface's engine signing and the SDK's
+ * execution planner both read it, so the two never sign different floors for
+ * the same quote.
+ *
+ * @param options.quotedAmount - the hop's quoted output, in the output token's base units
+ * @param options.slippageBasisPoints - the allowance, in basis points (100 is 1%)
+ * @returns the minimum output the swap accepts
+ */
+const swapMinimumOut = ({ quotedAmount, slippageBasisPoints, }) => (quotedAmount * (10000n - slippageBasisPoints)) / 10000n;
+exports.swapMinimumOut = swapMinimumOut;