@gibs/quotes 1.13.0 → 1.13.1

package/dist/search/enumerate.js

@@ -93,7 +93,13 @@ const resolveHopOutcome = (options) => {
         return {
             kind: 'delivered',
             deliveredAmount: exactResult.deliveredAmount,
-            outcome: { kind: 'quote', deliveredAmount: exactResult.deliveredAmount },
+            outcome: exactResult.priceImpactPercent === undefined
+                ? { kind: 'quote', deliveredAmount: exactResult.deliveredAmount }
+                : {
+                    kind: 'quote',
+                    deliveredAmount: exactResult.deliveredAmount,
+                    priceImpactPercent: exactResult.priceImpactPercent,
+                },
         };
     }
     if (carrier?.estimate !== undefined) {

package/dist/search/serve.d.ts

@@ -1,4 +1,4 @@
-import { type ComposedRouteVerdict, type PlannedHop, type RoutePlan } from '@gibs/bridge-sdk/routing';
+import { type ComposedRouteVerdict, type GasCostFor, type HopCarrier, type PlannedHop, type RoutePlan } from '@gibs/bridge-sdk/routing';
 /**
  * Decides whether a priced {@link RoutePlan} may be served to a reader as a
  * route they can sign — the boundary between the route-search engine
@@ -79,15 +79,6 @@ export type ServableWithheldReason = {
     readonly kind: 'too-many-signatures';
     readonly signatureCount: number;
     readonly maxSignatures: number;
-} | {
-    /**
-     * A section other than the first starts on a chain the reader holds no
-     * native gas on, and the hop landing there does not deliver native
-     * coin either — so the reader would have nothing to pay that section's
-     * own signature with.
-     */
-    readonly kind: 'gasless-middle-chain';
-    readonly chainId: number;
 } | {
     /**
      * The reader named a recipient other than their own wallet for a
@@ -103,6 +94,42 @@ export type ServableWithheldReason = {
     readonly kind: 'quality';
     readonly verdict: ComposedRouteVerdict | null;
 };
+/**
+ * One gas top-up a served plan needs: a section other than the first starts
+ * on a chain where the reader holds no native gas, and the previous section
+ * does not land native coin there. The reader must get gas on that chain
+ * before they can sign the section.
+ *
+ * A PART OF THE ROUTE, NEVER A REASON TO WITHHOLD IT. The owner: "if the user
+ * needs gas, then they should get it" — a gas top-up is a scored part of the
+ * route. The ranking already charges {@link estimatedCostAmount} (as the
+ * `refuelAmount` of the same `GasCostFor`); this record is what a host shows
+ * the reader so the charge is not invisible.
+ *
+ * NO PROVIDER CARRIES THE TOP-UP TODAY. No descriptor in `@gibs/bridge-sdk`'s
+ * provider registry declares a refuel or native-drop capability, so the top-up
+ * is a requirement the host presents, not a hop inside the plan.
+ */
+export type GasTopUp = {
+    /** 0-based index into `plan.signatures` of the section that needs the gas. */
+    readonly sectionIndex: number;
+    /** The chain the reader needs native gas on. */
+    readonly chainId: number;
+    /** The carrier the reader signs with on that chain — the section's first hop. */
+    readonly carrier: HopCarrier;
+    /**
+     * The native coin the section's signature burns, in that chain's native
+     * base units — the least the top-up must land. Null when the host passed no
+     * {@link ServableContext.gasCostFor}, or its quote carries no native figure.
+     */
+    readonly nativeAmountNeeded: bigint | null;
+    /**
+     * What getting that gas costs the reader, in the plan's destination token's
+     * base units — the same `refuelAmount` the ranking subtracts. Null when the
+     * host passed no {@link ServableContext.gasCostFor}.
+     */
+    readonly estimatedCostAmount: bigint | null;
+};
 /** The verdict {@link servableVerdict} returns. */
 export type ServableVerdict = {
     readonly kind: 'servable';
@@ -110,6 +137,12 @@ export type ServableVerdict = {
     readonly firstSectionRequest: FirstSectionRequest;
     /** Who signs the first section. */
     readonly leg: PlanFirstLegKind;
+    /**
+     * Every gas top-up the plan needs, in section order — empty when the
+     * reader can pay gas for every section. A host must show each one
+     * with the route; see {@link GasTopUp}.
+     */
+    readonly gasTopUps: readonly GasTopUp[];
 } | {
     readonly kind: 'withheld';
     readonly reason: ServableWithheldReason;
@@ -133,19 +166,38 @@ export type ServableContext = {
     readonly customRecipientSectionIndexes: ReadonlySet<number>;
     /**
      * The composed-route quality verdict for this plan (`assessComposedRoute`,
-     * `@gibs/bridge-sdk/routing`). Read only when the plan has more than one
-     * signature — a single-signature plan strands the reader nowhere between
-     * signatures, so the gate this verdict feeds does not apply to it. `null`
-     * or omitted means "not priced yet," which withholds a multi-signature
-     * plan exactly as a `'rejected'` verdict would.
+     * `@gibs/bridge-sdk/routing`). A plan with more than one signature is
+     * always gated: `null` or omitted means "not priced yet," which withholds
+     * it exactly as a `'rejected'` verdict would. A single-signature plan
+     * strands the reader nowhere between signatures, so it is gated only when
+     * the host passes a verdict (a swap that loses real value is still a bad
+     * offer); `null` or omitted, the gate does not apply to it.
      */
     readonly qualityVerdict?: ComposedRouteVerdict | null;
     /** Overrides the signature-count ceiling. Defaults to {@link MAX_SERVABLE_SIGNATURES}. */
     readonly maxSignatures?: number;
+    /**
+     * The SAME gas model the search ranked with (`@gibs/bridge-sdk/routing`'s
+     * `GasCostFor`). It prices each {@link GasTopUp}. Omitted, a top-up is
+     * still reported, with its amounts null.
+     */
+    readonly gasCostFor?: GasCostFor;
 };
+/**
+ * Lists the gas top-ups `plan` needs — see {@link GasTopUp}. A section needs
+ * one when it is not the first, its chain is in `gaslessChainIds`, and the
+ * previous section does not land native coin there
+ * (`sectionIsFundedByLanding`).
+ *
+ * @param plan - the plan to inspect
+ * @param context - the reader's gasless chains, and optionally the gas model
+ *   that prices each top-up
+ * @returns every top-up, in section order; empty when none is needed
+ */
+export declare const planGasTopUps: (plan: RoutePlan, context: Pick<ServableContext, "gaslessChainIds" | "gasCostFor">) => readonly GasTopUp[];
 /**
  * Decides whether `plan` may be served to a reader as a route they can sign
- * right now, against the five reasons a route can be held back:
+ * right now, against the four reasons a route can be held back:
  *
  * 1. **`unconfirmed`** — some hop still rests on an estimate, not a live
  *    quote (`planIsConfirmed`).
@@ -153,16 +205,18 @@ export type ServableContext = {
  *    {@link ServableContext.maxSignatures} allows.
  * 3. **`middle-recipient-not-reader`** — a non-last section would land
  *    somewhere other than the reader's own wallet.
- * 4. **`gasless-middle-chain`** — a non-first section starts on a chain the
- *    reader cannot pay gas on, and nothing lands native coin there to cover
- *    it.
- * 5. **`quality`** — a composed, multi-signature plan fails the value-loss
+ * 4. **`quality`** — a composed, multi-signature plan fails the value-loss
  *    gate (`assessComposedRoute`).
  *
  * Checked in that order; the first failing check is the reason returned. A
- * plan that clears all five is `'servable'`, carrying the first section's
- * hops and the first-hop signer kind ({@link planFirstLegKind}) so a host can
- * go build the real signing request.
+ * plan that clears all four is `'servable'`, carrying the first section's
+ * hops, the first-hop signer kind ({@link planFirstLegKind}), and every gas
+ * top-up the reader needs ({@link planGasTopUps}) so a host can go build the
+ * real signing request and show what the route asks of the reader.
+ *
+ * A GASLESS MIDDLE CHAIN NEVER WITHHOLDS A PLAN. It used to; the owner ruled
+ * that "a gas top-up is a scored part of the route, never a reason to
+ * withhold." The plan is served with a {@link GasTopUp} instead.
  *
  * THROWS, RATHER THAN RETURNING A VERDICT, FOR A MALFORMED PLAN — an empty
  * plan, or one that fails {@link sectionHandoverAgrees}. Both name a defect

package/dist/search/serve.js

@@ -1,5 +1,4 @@
-import { isNativeAsset } from '@gibs/bridge-sdk/ecosystems';
-import { assetNodeKey, composedRouteMayBeOffered, isRateLimitedCarrier, planIsConfirmed, } from '@gibs/bridge-sdk/routing';
+import { assetNodeKey, composedRouteMayBeOffered, isRateLimitedCarrier, planIsConfirmed, sectionIsFundedByLanding, } from '@gibs/bridge-sdk/routing';
 /**
  * Reads {@link PlanFirstLegKind} off a plan's FIRST hop only.
  *
@@ -61,9 +60,40 @@ export const sectionHandoverAgrees = (plan) => {
 };
 /** Owner decision, 2026-09-23: "minimize the steps, but if you have to go through 3 ... that is what you have to do." */
 export const MAX_SERVABLE_SIGNATURES = 3;
+/**
+ * Lists the gas top-ups `plan` needs — see {@link GasTopUp}. A section needs
+ * one when it is not the first, its chain is in `gaslessChainIds`, and the
+ * previous section does not land native coin there
+ * (`sectionIsFundedByLanding`).
+ *
+ * @param plan - the plan to inspect
+ * @param context - the reader's gasless chains, and optionally the gas model
+ *   that prices each top-up
+ * @returns every top-up, in section order; empty when none is needed
+ */
+export const planGasTopUps = (plan, context) => plan.signatures.flatMap((group, sectionIndex) => {
+    const firstHop = plan.hops[group[0] ?? -1];
+    if (sectionIndex === 0 || firstHop === undefined)
+        return [];
+    const { chainId } = firstHop.edge.from;
+    if (!context.gaslessChainIds.has(chainId))
+        return [];
+    if (sectionIsFundedByLanding(plan, sectionIndex))
+        return [];
+    const quote = context.gasCostFor?.(chainId, firstHop.edge.carrier);
+    return [
+        {
+            sectionIndex,
+            chainId,
+            carrier: firstHop.edge.carrier,
+            nativeAmountNeeded: quote?.nativeGasAmount ?? null,
+            estimatedCostAmount: quote?.refuelAmount ?? null,
+        },
+    ];
+});
 /**
  * Decides whether `plan` may be served to a reader as a route they can sign
- * right now, against the five reasons a route can be held back:
+ * right now, against the four reasons a route can be held back:
  *
  * 1. **`unconfirmed`** — some hop still rests on an estimate, not a live
  *    quote (`planIsConfirmed`).
@@ -71,16 +101,18 @@ export const MAX_SERVABLE_SIGNATURES = 3;
  *    {@link ServableContext.maxSignatures} allows.
  * 3. **`middle-recipient-not-reader`** — a non-last section would land
  *    somewhere other than the reader's own wallet.
- * 4. **`gasless-middle-chain`** — a non-first section starts on a chain the
- *    reader cannot pay gas on, and nothing lands native coin there to cover
- *    it.
- * 5. **`quality`** — a composed, multi-signature plan fails the value-loss
+ * 4. **`quality`** — a composed, multi-signature plan fails the value-loss
  *    gate (`assessComposedRoute`).
  *
  * Checked in that order; the first failing check is the reason returned. A
- * plan that clears all five is `'servable'`, carrying the first section's
- * hops and the first-hop signer kind ({@link planFirstLegKind}) so a host can
- * go build the real signing request.
+ * plan that clears all four is `'servable'`, carrying the first section's
+ * hops, the first-hop signer kind ({@link planFirstLegKind}), and every gas
+ * top-up the reader needs ({@link planGasTopUps}) so a host can go build the
+ * real signing request and show what the route asks of the reader.
+ *
+ * A GASLESS MIDDLE CHAIN NEVER WITHHOLDS A PLAN. It used to; the owner ruled
+ * that "a gas top-up is a scored part of the route, never a reason to
+ * withhold." The plan is served with a {@link GasTopUp} instead.
  *
  * THROWS, RATHER THAN RETURNING A VERDICT, FOR A MALFORMED PLAN — an empty
  * plan, or one that fails {@link sectionHandoverAgrees}. Both name a defect
@@ -116,16 +148,8 @@ export const servableVerdict = (plan, context) => {
             return { kind: 'withheld', reason: { kind: 'middle-recipient-not-reader', sectionIndex } };
         }
     }
-    for (let sectionIndex = 1; sectionIndex < plan.signatures.length; sectionIndex += 1) {
-        const previousGroup = plan.signatures[sectionIndex - 1];
-        const landingHop = plan.hops[previousGroup[previousGroup.length - 1]];
-        const landingNode = landingHop.edge.to;
-        const landsNativeCoin = isNativeAsset(landingNode.address, landingNode.ecosystem);
-        if (!landsNativeCoin && context.gaslessChainIds.has(landingNode.chainId)) {
-            return { kind: 'withheld', reason: { kind: 'gasless-middle-chain', chainId: landingNode.chainId } };
-        }
-    }
-    if (plan.signatures.length > 1) {
+    const gateApplies = plan.signatures.length > 1 || (context.qualityVerdict ?? null) !== null;
+    if (gateApplies) {
         const verdict = context.qualityVerdict ?? null;
         const passesQualityGate = verdict !== null && composedRouteMayBeOffered(verdict);
         if (!passesQualityGate) {
@@ -138,5 +162,6 @@ export const servableVerdict = (plan, context) => {
         kind: 'servable',
         firstSectionRequest: { hops: firstSectionHops, inputAmount: context.amount },
         leg: planFirstLegKind(plan),
+        gasTopUps: planGasTopUps(plan, context),
     };
 };

package/dist/search/waves.js

@@ -330,13 +330,15 @@ const recomposePath = (path, startAmount, askedAmountForHop, cache) => {
         // ever deliver. The difference stays in the reader's wallet unspent.
         runningAmount = hop.edge.fusesNext && minimumDeliveredAmount !== null ? minimumDeliveredAmount : deliveredAmount;
         const refusalReason = refusalReasonByHopIndex[index] ?? null;
+        const measuredImpact = hop.outcome.priceImpactPercent;
+        const impactField = measuredImpact === undefined ? {} : { priceImpactPercent: measuredImpact };
         const outcome = figureHop.figure.kind === 'quote'
             ? minimumDeliveredAmount === null
-                ? { kind: 'quote', deliveredAmount }
-                : { kind: 'quote', deliveredAmount, minimumDeliveredAmount }
+                ? { kind: 'quote', deliveredAmount, ...impactField }
+                : { kind: 'quote', deliveredAmount, minimumDeliveredAmount, ...impactField }
             : refusalReason === null
-                ? { kind: 'estimate', deliveredAmount, basis: figureHop.figure.basis }
-                : { kind: 'estimate', deliveredAmount, basis: figureHop.figure.basis, refusalReason };
+                ? { kind: 'estimate', deliveredAmount, basis: figureHop.figure.basis, ...impactField }
+                : { kind: 'estimate', deliveredAmount, basis: figureHop.figure.basis, refusalReason, ...impactField };
         updatedHops.push({ ...hop, outcome });
     }
     return { ...path, hops: updatedHops };

package/dist/types.d.ts

@@ -129,6 +129,8 @@ export type ExactHopResult = {
     readonly outcome: 'delivered';
     /** What this edge delivers for exactly the requested input amount, in `to`'s base units. */
     readonly deliveredAmount: bigint;
+    /** How far this edge's executed rate falls below its marginal rate, in percent; absent when the carrier cannot measure it. */
+    readonly priceImpactPercent?: number;
 } | {
     readonly outcome: 'refused';
     /** Why this carrier's own data says the amount cannot cross. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gibs/quotes",
-  "version": "1.13.0",
+  "version": "1.13.1",
   "description": "Isomorphic core for asking cross-chain bridge aggregators (LI.FI, Relay, NEAR Intents) for display and execution quotes — the wire contract, refusal reading, and the shared guards a host wraps every upstream call in. Runs unchanged in a browser or in Node.",
   "keywords": [
     "ethereum",
@@ -122,7 +122,7 @@
     "typecheck": "npx tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@gibs/bridge-sdk": "^1.13.0",
+    "@gibs/bridge-sdk": "^1.13.1",
     "zod": "^3.25.76"
   },
   "peerDependencies": {