@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/routing/search/score.d.ts

@@ -0,0 +1,324 @@
+import { type ComposedPathBasis, type HopCarrier, type RoutePlan } from './graph.js';
+/**
+ * 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 declare const waitPenaltyPpm: (durationSeconds: number | null | undefined) => number;
+/**
+ * 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 declare const SIGNATURE_PENALTY_PPM = 2500;
+/**
+ * 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 declare 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 declare const GAS_TOPUP_PENALTY_PPM = 10000;
+/**
+ * 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 declare const GAS_TOPUP_PENALTY_FLOOR_USD = 3;
+/**
+ * What {@link scoreRoutePlan} needs to rank one priced route plan.
+ *
+ * EVERY FIELD IS A PLAIN, ALREADY-COMPUTED VALUE — never a {@link RoutePlan}
+ * itself. A route plan (`graph.ts`) names the STRUCTURE of a path; it carries
+ * no dollar price and no wallet gas balance, because pricing needs a live
+ * quote or a price feed and a gas balance needs a connected wallet, neither
+ * of which this pure module has access to. The caller — Phase 1's
+ * `plan-route-data.ts`, or today's `producers.ts` once it adopts this
+ * function — is responsible for turning a priced `RoutePlan` into these
+ * fields:
+ *
+ *  - {@link deliveredUsd}, {@link paidUsd}, {@link outsideFeesUsd} come from
+ *    the same valuation `producers.ts` already performs per candidate
+ *    (`candidateDeliveredUsd`, `candidatePaidUsd`, `candidateOutsideFeesUsd`),
+ *    generalized to the plan's LAST hop and FIRST hop respectively;
+ *  - {@link legClaimedDurationsSeconds} is one entry per hop, in hop order,
+ *    holding each hop's own carrier-claimed execution duration;
+ *  - {@link readerActionCount} is `plan.signatures.length` for a
+ *    `RoutePlan` built by `graph.ts`'s `groupHopsBySignature` — that
+ *    function's own doc is explicit that a pay-by-hand hop starts a group
+ *    exactly like a signing hop does, which is what makes the group COUNT
+ *    already equal the reader ACTION count design section 4 calls `A`;
+ *  - {@link gaslessIntermediateChainCount} is `G` from design section 4 — the
+ *    count of intermediate chains where the connected account holds no gas —
+ *    which needs a multi-chain wallet balance read this module cannot
+ *    perform itself.
+ */
+export type RouteScoreInputs = {
+    /**
+     * What the route delivers at the destination, in United States dollars —
+     * `D` in the route-search design's section 4 formula. Generalizes
+     * `candidateDeliveredUsd` (`../producers.js`) from one candidate to a
+     * plan's final hop.
+     */
+    readonly deliveredUsd: number;
+    /**
+     * What the reader pays for the route's origin leg, in United States
+     * dollars — `P` in the design formula. Generalizes `candidatePaidUsd`
+     * (`../producers.js`, there private as `candidatePaidUsd`) to a plan's
+     * first hop.
+     */
+    readonly paidUsd: number;
+    /**
+     * Every charge levied outside the origin amount, in United States dollars
+     * — `F` in the design formula. Generalizes `candidateOutsideFeesUsd`
+     * (`../producers.js`).
+     */
+    readonly outsideFeesUsd: number;
+    /**
+     * Each hop's own carrier-claimed execution duration, in seconds, in hop
+     * order — one entry per hop in the plan, whatever the hop's carrier or
+     * signature group. `null`/`undefined` entries are hops with no claimed
+     * duration, exactly as {@link waitPenaltyPpm} already treats a missing
+     * claim: zero penalty, not the worst case.
+     */
+    readonly legClaimedDurationsSeconds: readonly (number | null | undefined)[];
+    /**
+     * How many separate actions the reader performs to carry out this plan —
+     * `A` in the design formula. A signature and a pay-by-hand deposit each
+     * count as one action; see this type's own doc for how to derive it from a
+     * `RoutePlan`.
+     */
+    readonly readerActionCount: number;
+    /**
+     * How many of the plan's intermediate chains the connected account holds
+     * no gas on — `G` in the design formula.
+     */
+    readonly gaslessIntermediateChainCount: number;
+    /**
+     * PHASE 3 — what grounds {@link deliveredUsd}: the plan's own
+     * {@link ComposedPathBasis} (`graph.ts`), the WORST basis across every hop
+     * composed — build it with `planComposedBasis` (`graph.ts`) rather than by
+     * hand. REQUIRED, not optional: a caller building `RouteScoreInputs` from a
+     * `RoutePlan` always has this, and letting it be omitted would silently
+     * reopen the exact defect PHASE 3 closes elsewhere in this search — a
+     * `deliveredUsd` computed from an `'unpriced'` figure (see
+     * `EstimateBasis`'s own doc, `graph.ts`: "a bare decimal rescale... with no
+     * value behind it") scored and compared as if it meant something. See
+     * {@link scoreRoutePlan}'s own doc for what it does with this.
+     */
+    readonly basis: ComposedPathBasis;
+};
+/**
+ * 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 declare const compareRoutePlansByScoreAdjustedDeliveredAmount: (a: RoutePlan, b: RoutePlan) => number;
+export declare const scoreRoutePlan: (inputs: RouteScoreInputs) => number;
+/**
+ * What one signature (one wallet prompt, or one pay-by-hand deposit that
+ * still needs the chain's own gas to have been acquired first) costs beyond
+ * what the route's own steps already net out — already converted into the
+ * PLAN'S OWN destination token's base units, so it can be subtracted straight
+ * from a `RoutePlan`'s last-hop `deliveredAmount` alongside every other
+ * signature's own cost.
+ */
+export type GasCostQuote = {
+    /**
+     * Gas units × gas price × native price, for the chain this signature
+     * broadcasts on, converted into the destination token. Charged for EVERY
+     * signature, never only the extra ones — the owner's own instruction: "gas
+     * for every signature," not a discount for the first one the way
+     * {@link SIGNATURE_PENALTY_PPM} discounts only signatures beyond the first.
+     */
+    readonly gasAmount: bigint;
+    /**
+     * The cost of acquiring native gas first, when the signer holds none on
+     * this chain — a small aggregator or PulseX step to native, or a
+     * provider's own refuel field. Zero when no top-up is needed.
+     *
+     * NEVER A REASON TO WITHHOLD THE ROUTE. The owner: "it should be scored, if
+     * the user needs gas, then they should get it" — a gasless intermediate
+     * chain is modelled as ONE MORE CHARGE against the route, exactly like the
+     * gas itself, never as a refusal or an exclusion from the ranking.
+     */
+    readonly refuelAmount: bigint;
+};
+/**
+ * Supplies the REAL cost of signing one step, for the chain it broadcasts on
+ * and the carrier performing it — gas units × gas price × native price,
+ * converted into the plan's own destination token, plus a refuel cost when
+ * the signer holds no native gas there yet. PLUGGABLE ON PURPOSE: this
+ * module has no gas-price oracle, no native-token price feed, and no wallet
+ * balance read of its own — the caller (which has all three, and the plan's
+ * own destination-token price to convert into) is the one place that can
+ * answer this, exactly as `waves.ts`'s own `AskEdge` is caller-supplied for
+ * the same reason. `sender` is the {@link HopCarrier} performing the
+ * signature's own FIRST hop — structurally the same vocabulary
+ * `@gibs/quotes`'s `CarrierSender`/`Carrier.id` already carry, passed as a
+ * plain string here (not imported) for the same circular-package-dependency
+ * reason `search/carriers/omnibridge.ts`'s own head doc explains: this
+ * caller-supplied function is free to look the carrier up in its own
+ * registry and pick a gas-unit model "per sender kind" from there (an
+ * omnibridge entry call, a PulseX swap, and an aggregator's own executed
+ * transaction each cost a genuinely different amount of gas).
+ *
+ * @param chainId - the chain this signature is broadcast on — the signing
+ *   hop's `from.chainId`
+ * @param sender - the carrier performing the signature's first hop
+ * @returns the signature's real cost, in the plan's destination token's base units
+ */
+export type GasCostFor = (chainId: number, sender: HopCarrier) => GasCostQuote;
+/**
+ * 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 declare const zeroGasCostFor: GasCostFor;
+/**
+ * `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. 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 declare const gasAdjustedDeliveredAmount: (plan: RoutePlan, gasCostFor: GasCostFor) => bigint;
+/**
+ * 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 declare const compareRoutePlansByGasAdjustedDeliveredAmount: (gasCostFor: GasCostFor) => (a: RoutePlan, b: RoutePlan) => number;