@gibs/bridge-sdk 1.18.0 → 1.20.0

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

@@ -3,70 +3,8 @@ 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;
@@ -76,185 +14,13 @@ const waitPenaltyPpm = (durationSeconds) => {
     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);
@@ -262,45 +28,6 @@ const signaturePenaltyAdjustedDeliveredAmount = (plan) => {
     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);
@@ -331,34 +58,8 @@ const scoreRoutePlan = (inputs) => {
         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;
@@ -369,20 +70,6 @@ const sectionIsFundedByLanding = (plan, sectionIndex) => {
     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) => {
@@ -398,32 +85,6 @@ const gasAdjustedDeliveredAmount = (plan, gasCostFor) => {
     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);
@@ -435,11 +96,6 @@ const compareRoutePlansByGasAdjustedDeliveredAmount = (gasCostFor) => (a, b) =>
     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.js

@@ -5,50 +5,7 @@ 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;
@@ -74,25 +31,6 @@ const buildPulseXSwapTransaction = (options) => {
     });
 };
 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) {
@@ -100,8 +38,6 @@ const buildWrapTransaction = (options) => {
     }
     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;
     }
@@ -119,15 +55,5 @@ const buildWrapTransaction = (options) => {
     };
 };
 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;

package/dist/cjs/routing/usd-value.js

@@ -2,18 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.usdValueOfAmount = void 0;
 const viem_1 = require("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
- */
 const usdValueOfAmount = (params) => {
     const { balance, decimals, price } = params;
     if (price === null)