@gibs/bridge-sdk 1.12.0 → 1.13.1

package/dist/routing/candidate-route.d.ts

@@ -0,0 +1,43 @@
+import type { RouteCandidate } from './candidate.js';
+import type { RouteData } from './route-data.js';
+/**
+ * One door in front of the two base route builders.
+ *
+ * WHY THIS EXISTS. A candidate is drawn by one of two builders and the choice
+ * is not the caller's to make by hand. {@link buildCandidateRouteData} draws a
+ * candidate as ONE signature, because the aggregator's executor performs the
+ * omnibridge entry call on arrival. {@link buildNearIntentsTwoStepRouteData}
+ * draws it as TWO, because the aggregator that carried it cannot execute
+ * anything on the chain it delivers to, so the reader signs the crossing
+ * themselves.
+ *
+ * Every composer that builds on top of a candidate — the PulseX conversion
+ * route is the first — has to pick between them, and picking wrong is not a
+ * cosmetic error. A two-signature candidate run through the one-signature
+ * builder produces a route that claims the crossing happens inside the
+ * transaction the reader already signed. It does not. The reader would select
+ * that route, sign once, and be left holding the anchor token on the entry
+ * chain with the interface reporting the journey finished.
+ *
+ * `candidate.deferredCrossing` is the fact that decides it, and it is the same
+ * field {@link buildNearIntentsTwoStepRouteData} refuses to build without. So
+ * the two agree by construction rather than by two callers remembering the
+ * same rule.
+ *
+ * @param candidate - the priced route candidate
+ * @returns the raw route data, or null when the candidate names a deferred
+ *   crossing but no omnibridge provider to perform it
+ */
+export declare const buildRouteDataForCandidate: (candidate: RouteCandidate) => RouteData | null;
+/**
+ * How many wallet signatures a raw route asks the reader for.
+ *
+ * Counts the sections, because one section is one signature — that is what a
+ * section means. Named rather than left as `sections.length` at each call
+ * site, so a surface that warns about a long journey and a surface that ranks
+ * routes cannot come to different counts.
+ *
+ * @param route - the raw route data
+ * @returns the number of signatures, one per section
+ */
+export declare const routeSignatureCount: (route: RouteData) => number;

package/dist/routing/candidate-route.js

@@ -0,0 +1,45 @@
+import { buildNearIntentsTwoStepRouteData } from '../near-intents-route.js';
+import { buildCandidateRouteData } from './producers.js';
+/**
+ * One door in front of the two base route builders.
+ *
+ * WHY THIS EXISTS. A candidate is drawn by one of two builders and the choice
+ * is not the caller's to make by hand. {@link buildCandidateRouteData} draws a
+ * candidate as ONE signature, because the aggregator's executor performs the
+ * omnibridge entry call on arrival. {@link buildNearIntentsTwoStepRouteData}
+ * draws it as TWO, because the aggregator that carried it cannot execute
+ * anything on the chain it delivers to, so the reader signs the crossing
+ * themselves.
+ *
+ * Every composer that builds on top of a candidate — the PulseX conversion
+ * route is the first — has to pick between them, and picking wrong is not a
+ * cosmetic error. A two-signature candidate run through the one-signature
+ * builder produces a route that claims the crossing happens inside the
+ * transaction the reader already signed. It does not. The reader would select
+ * that route, sign once, and be left holding the anchor token on the entry
+ * chain with the interface reporting the journey finished.
+ *
+ * `candidate.deferredCrossing` is the fact that decides it, and it is the same
+ * field {@link buildNearIntentsTwoStepRouteData} refuses to build without. So
+ * the two agree by construction rather than by two callers remembering the
+ * same rule.
+ *
+ * @param candidate - the priced route candidate
+ * @returns the raw route data, or null when the candidate names a deferred
+ *   crossing but no omnibridge provider to perform it
+ */
+export const buildRouteDataForCandidate = (candidate) => candidate.deferredCrossing
+    ? buildNearIntentsTwoStepRouteData(candidate)
+    : buildCandidateRouteData(candidate);
+/**
+ * How many wallet signatures a raw route asks the reader for.
+ *
+ * Counts the sections, because one section is one signature — that is what a
+ * section means. Named rather than left as `sections.length` at each call
+ * site, so a surface that warns about a long journey and a surface that ranks
+ * routes cannot come to different counts.
+ *
+ * @param route - the raw route data
+ * @returns the number of signatures, one per section
+ */
+export const routeSignatureCount = (route) => route.sections.length;

package/dist/routing/candidate.d.ts

@@ -0,0 +1,237 @@
+import type { ConsolidatedQuote, ConsolidatedQuoteRequest } from '../consolidated-quote.js';
+import type { Provider } from '../config.js';
+import type { Token } from '../types.js';
+import type { RoutePlan } from './search/graph.js';
+/**
+ * One priced route candidate: the consolidated (aggregator) quote for the leg
+ * from the source chain to an omnibridge entry point, paired with the context
+ * needed to describe the omnibridge leg that carries it the rest of the way to
+ * PulseChain. The hook builds one of these per entry point it can quote.
+ */
+export type RouteCandidate = {
+    /** Stable identity for keys and selection, unique within one strip render. */
+    id: string;
+    /** The aggregator quote for the source → entry-point leg. */
+    quote: ConsolidatedQuote;
+    /**
+     * The bridge provider that crosses from the entry point to PulseChain.
+     *
+     * NULL ON A ROUTE THAT CROSSES NO BRIDGE. A candidate whose destination the
+     * omnibridge does not reach is carried entirely by the aggregator: there is
+     * no second leg, so there is no bridge to name. Null rather than a stand-in
+     * string, because every reader of this field is asking which bridge performs
+     * that leg, and naming one that is not involved is worse than saying nothing.
+     *
+     * Typed `Provider | null`, not `string | null` — the source is
+     * `omnibridgeProviderForEntryChain`, which already returns `Provider | null`.
+     */
+    omnibridgeProvider: Provider | null;
+    /** The chain the omnibridge leg starts on (the entry point: Ethereum or BSC). */
+    entryChainId: number;
+    /**
+     * The source token the user pays with. Its symbol and resolvable image render
+     * the SOURCE node of the route's collapsed token flow — without it the source
+     * node would have no symbol (the normalized quote step carries only a raw token
+     * address) and no logo.
+     */
+    originToken: Token;
+    /** The token the user receives on PulseChain (the route's delivered token). */
+    destinationToken: Token;
+    /**
+     * The amount delivered on PulseChain after the omnibridge crossing fee, in base
+     * units. The aggregator delivers the request's `toAmount` onto the entry chain;
+     * the omnibridge takes its crossing fee before it lands, so this is the NET the
+     * user receives — and the directly comparable "amount delivered" the routes
+     * rank on (cheapest total wins).
+     */
+    deliveredAmount: bigint;
+    /**
+     * The omnibridge crossing fee in delivered-token base units — the amount the
+     * omnibridge takes between the entry chain and PulseChain (`toAmount` minus
+     * {@link deliveredAmount}). Carried so the route's detail view can show the
+     * BSC→PulseChain / Ethereum→PulseChain crossing fee as its OWN line, computed
+     * from the known on-chain fee rate rather than inferred from a price spread.
+     * Zero when the fee rate has not loaded.
+     */
+    omnibridgeFeeAmount: bigint;
+    /** Per-PulseChain-token United States dollar price, or null when unpriced. */
+    destinationUsdPrice: number | null;
+    /**
+     * The amount the user actually TYPED, in origin token base units — as distinct
+     * from `quote.fromAmount`, which is what the quote turned out to need.
+     *
+     * The two differ because the quote is solved BACKWARD to a delivery target, and
+     * that target is the provider's guaranteed floor rather than its expectation.
+     * Backward-solving to the floor consumes less than was typed, and the remainder
+     * stays in the user's wallet. Carried here so the route can NAME that remainder
+     * instead of letting it show up as an unexplained gap between the amount the
+     * form prices and the value the route reports delivering.
+     *
+     * Null or absent when the caller does not know it; the route then says nothing
+     * about unspent tokens rather than guessing at a figure.
+     */
+    requestedAmount?: bigint | null;
+    /**
+     * The crossing the reader has to come back and sign for themselves.
+     *
+     * ABSENT ON EVERY ROUTE THAT TAKES ONE SIGNATURE, which is nearly all of
+     * them. An aggregator that can execute a call on the chain it delivers to is
+     * handed the omnibridge entry call, performs it on arrival, and the whole
+     * journey is one signature — so there is no second crossing to describe.
+     *
+     * Present when the aggregator CANNOT execute on arrival. It then delivers the
+     * anchor token into the reader's own wallet on the entry chain and stops, and
+     * the omnibridge crossing becomes a second signature the reader makes later.
+     * The route must say so on its face rather than in a tooltip, which is what
+     * this field drives: see `buildNearIntentsTwoStepRouteData`.
+     *
+     * It carries the ANCHOR — what lands on the entry chain — because nothing
+     * else on this candidate does. `destinationToken` is the far side of the
+     * crossing and `originToken` the near side of the swap; the token in the
+     * middle, which is the thing the reader is left holding between the two
+     * signatures, appears nowhere else.
+     */
+    deferredCrossing?: DeferredCrossing | null;
+    /**
+     * The consolidated quote REQUEST this candidate's `quote` actually answers,
+     * when that differs from the entry's shared one-signature `request`.
+     *
+     * ABSENT ON EVERY ONE-SIGNATURE CANDIDATE. Every candidate quoted through the
+     * competed field (`quotedCandidates` in `useRouteOptions.ts`) answers that
+     * entry's own `request` — the omnibridge entry call aimed at PulseChain — so
+     * the caller already has the right request and this field would only repeat
+     * it.
+     *
+     * PRESENT ON A TWO-STEP CANDIDATE (one with {@link deferredCrossing} set).
+     * That candidate's `quote` answers a DIFFERENT question — `twoStepRequest`
+     * in `useRouteOptions.ts`, which targets the ENTRY chain and the reader's
+     * own wallet, not PulseChain. A caller that re-quotes or records against the
+     * entry's shared `request` instead would ask a live provider to reprice a
+     * PulseChain delivery this candidate never offered, and would write a resume
+     * record naming the wrong destination token and chain. Every caller that
+     * commits or records a SELECTED candidate must read `quoteRequest` first and
+     * fall back to the entry's `request` only when this is absent.
+     */
+    quoteRequest?: ConsolidatedQuoteRequest;
+    /**
+     * The general-search plan this candidate was built from, when it came from
+     * one — see the route-search design, section 1.
+     *
+     * ABSENT ON EVERY CANDIDATE PHASE 0 PRODUCES. Nothing builds a
+     * {@link RoutePlan} yet; the field exists so the shape it will fill is
+     * fixed before Phase 1's `enumerate.ts` starts producing plans. This is
+     * ALSO WHY IT IS OPTIONAL RATHER THAN REQUIRED: today's producers
+     * (`useAggregatorRouteCandidate`, `buildDirectCrossingCandidate`,
+     * `buildNearIntentsTwoStepRouteData`'s caller, and every stored `History`
+     * record replayed through `storedShapes`) build a `RouteCandidate` with no
+     * plan at all, and a required field would break every one of them on this
+     * phase landing alone.
+     *
+     * ONCE A CANDIDATE CARRIES A PLAN, three fields above stop being
+     * independently set and are instead DERIVED from it, so there is exactly
+     * one source of truth for what the candidate's route actually does:
+     * - {@link deferredCrossing} — present when `plan.signatures` has more than
+     *   one group, taken from the first hop of the second group (the anchor
+     *   the reader is left holding between signatures).
+     * - {@link entryChainId} — the `to` node's `chainId` of the plan's last
+     *   hop whose carrier is `'pulsechain'` or `'tokensex'` (its bridge hop).
+     * - {@link omnibridgeProvider} — that same hop's `carrier`, or null when
+     *   the plan crosses no bridge hop at all (a route the omnibridge does not
+     *   reach, carried entirely by aggregators).
+     *
+     * A candidate built WITHOUT a plan keeps setting these three fields by
+     * hand, exactly as it does today; nothing about their existing meaning
+     * changes until a caller actually starts constructing plans.
+     */
+    plan?: RoutePlan;
+};
+/**
+ * The anchor a two-signature route leaves the reader holding between its legs.
+ *
+ * Named for the crossing that is deferred, not for the leg that is signed now,
+ * because the deferral is the fact a reader needs and the anchor is only how it
+ * is described.
+ */
+export type DeferredCrossing = {
+    /** The token that lands on the entry chain, in the reader's own wallet. */
+    anchorToken: Token;
+    /** How much of it lands, in that token's base units. */
+    anchorAmount: bigint;
+    /**
+     * What the aggregator says that landing is worth, in United States dollars.
+     *
+     * The aggregator's OWN figure for the delivered side, paired with its own
+     * figure for the paid side. Two price feeds disagree by more than a small
+     * route's whole fee, so a section's cost is only a cost when both ends come
+     * from one answer.
+     */
+    anchorUsdValue: string | null;
+};
+/**
+ * The inputs for {@link buildDirectCrossingCandidate}: the entry chain that equals
+ * the origin chain, the origin token paid on that chain, the anchor token delivered
+ * on PulseChain, the raw amount in, the origin token's United States dollar price,
+ * and the omnibridge crossing fee rate.
+ */
+export type DirectCrossingCandidateInputs = {
+    /** The omnibridge entry chain — MUST equal the origin chain for same-chain crossing. */
+    entryChainId: number;
+    /** The source chain the user's funds start on (equals entryChainId for this path). */
+    originChainId: number;
+    /** The source token the user pays with on the origin/entry chain. */
+    originToken: Token;
+    /**
+     * The anchor token delivered on PulseChain — the
+     * `effectiveEthereumDestination.pulsechainToken` or its Binance Smart Chain
+     * counterpart.
+     */
+    destinationToken: Token;
+    /** The raw amount the user is sending, in origin token base units. */
+    amountIn: bigint;
+    /** Per-origin-token United States dollar price, or null when unpriced. */
+    originUsdPrice: number | null;
+    /**
+     * Per-destination-token United States dollar price on PulseChain, or null when
+     * unpriced. Used to value the crossing fee and the delivered amount for ranking.
+     */
+    destinationUsdPrice: number | null;
+    /**
+     * The omnibridge foreign→home crossing fee rate (per 1e18) for this entry
+     * chain, or null when the fee config has not loaded.
+     */
+    omnibridgeFeePerEther: bigint | null;
+};
+/**
+ * Synthesizes a {@link RouteCandidate} for the SAME-CHAIN direct-omnibridge
+ * conversion case: when the origin chain IS one of the omnibridge entry chains
+ * (Ethereum chain 1 or Binance Smart Chain chain 56), there is no aggregator leg
+ * to quote — the user bridges directly from that chain to PulseChain. The
+ * same-chain skip in {@link useAggregatorRouteCandidate} is correct (nothing to
+ * quote), but it left the conversion path empty. This helper fills that gap by
+ * synthesizing a zero-step candidate that `usePulseXConversionRoutes` (the user
+ * interface's plural composer) can consume unchanged, producing the correct
+ * same-chain conversion route so the ranker can pick the cheapest option.
+ *
+ * The synthetic quote carries zero steps (no aggregator hops), a zero execution
+ * duration (the direct crossing needs no quote wait), and a null transaction
+ * request — this candidate is DISPLAY and RANKING only. The candidate's
+ * `deliveredAmount` is net of the omnibridge crossing fee, identical to the math
+ * {@link useAggregatorRouteCandidate} applies.
+ *
+ * This is a PURE exported helper (no hooks, no side effects) so it is
+ * unit-testable in isolation and can be called from two `useMemo` blocks in
+ * Bridge.tsx without duplicating the object literal.
+ *
+ * EXECUTION: when the route built from this candidate is selected, the
+ * consolidated (aggregator) execute path is deliberately NOT used — there is no
+ * aggregator leg for it to sign. `executesViaConsolidated`
+ * (`packages/ui/src/lib/state/bridgeExecution.ts`) recognizes the candidate's
+ * `entryChainId === originChainId` and routes the selection through the direct
+ * omnibridge sender instead, which builds its transaction from the live
+ * `useBridgeSettings` cascade rather than from this synthetic quote.
+ *
+ * @param inputs - the entry chain, origin/destination tokens, amount, and fee rate
+ * @returns the synthesized RouteCandidate, or throws when the entry chain is not
+ *   a valid omnibridge entry point (caller must guard on `omnibridgeProviderForEntryChain`)
+ */
+export declare const buildDirectCrossingCandidate: ({ entryChainId, originChainId, originToken, destinationToken, amountIn, originUsdPrice, destinationUsdPrice, omnibridgeFeePerEther, }: DirectCrossingCandidateInputs) => RouteCandidate;

package/dist/routing/candidate.js

@@ -0,0 +1,96 @@
+import { formatUnits } from 'viem';
+import { netDeliveredAmount } from './amounts.js';
+import { omnibridgeProviderForEntryChain } from './providers.js';
+/**
+ * Synthesizes a {@link RouteCandidate} for the SAME-CHAIN direct-omnibridge
+ * conversion case: when the origin chain IS one of the omnibridge entry chains
+ * (Ethereum chain 1 or Binance Smart Chain chain 56), there is no aggregator leg
+ * to quote — the user bridges directly from that chain to PulseChain. The
+ * same-chain skip in {@link useAggregatorRouteCandidate} is correct (nothing to
+ * quote), but it left the conversion path empty. This helper fills that gap by
+ * synthesizing a zero-step candidate that `usePulseXConversionRoutes` (the user
+ * interface's plural composer) can consume unchanged, producing the correct
+ * same-chain conversion route so the ranker can pick the cheapest option.
+ *
+ * The synthetic quote carries zero steps (no aggregator hops), a zero execution
+ * duration (the direct crossing needs no quote wait), and a null transaction
+ * request — this candidate is DISPLAY and RANKING only. The candidate's
+ * `deliveredAmount` is net of the omnibridge crossing fee, identical to the math
+ * {@link useAggregatorRouteCandidate} applies.
+ *
+ * This is a PURE exported helper (no hooks, no side effects) so it is
+ * unit-testable in isolation and can be called from two `useMemo` blocks in
+ * Bridge.tsx without duplicating the object literal.
+ *
+ * EXECUTION: when the route built from this candidate is selected, the
+ * consolidated (aggregator) execute path is deliberately NOT used — there is no
+ * aggregator leg for it to sign. `executesViaConsolidated`
+ * (`packages/ui/src/lib/state/bridgeExecution.ts`) recognizes the candidate's
+ * `entryChainId === originChainId` and routes the selection through the direct
+ * omnibridge sender instead, which builds its transaction from the live
+ * `useBridgeSettings` cascade rather than from this synthetic quote.
+ *
+ * @param inputs - the entry chain, origin/destination tokens, amount, and fee rate
+ * @returns the synthesized RouteCandidate, or throws when the entry chain is not
+ *   a valid omnibridge entry point (caller must guard on `omnibridgeProviderForEntryChain`)
+ */
+export const buildDirectCrossingCandidate = ({ entryChainId, originChainId, originToken, destinationToken, amountIn, originUsdPrice, destinationUsdPrice, omnibridgeFeePerEther, }) => {
+    const provider = omnibridgeProviderForEntryChain(entryChainId);
+    if (provider === null) {
+        throw new Error(`buildDirectCrossingCandidate: chain ${entryChainId} is not an omnibridge entry point`);
+    }
+    if (originChainId !== entryChainId) {
+        throw new Error(`buildDirectCrossingCandidate: originChainId must equal entryChainId (same-chain crossing only)`);
+    }
+    const delivered = netDeliveredAmount(amountIn, omnibridgeFeePerEther);
+    const omnibridgeFeeAmount = amountIn > delivered ? amountIn - delivered : 0n;
+    const fromAmountUsd = originUsdPrice !== null && amountIn > 0n
+        ? String(Number(formatUnits(amountIn, originToken.decimals)) * originUsdPrice)
+        : null;
+    const quoteId = `direct-omnibridge-${entryChainId}-${originChainId}`;
+    const syntheticQuote = {
+        // The synthetic quote wraps the omnibridge provider slug. ConsolidatedQuote's
+        // `provider` field is typed for the aggregator providers ('lifi' | 'relay'),
+        // but the functions that read it (`resolveProviderDisplayName`,
+        // `resolveProviderLogoUri`) accept any string at runtime. The cast is safe here
+        // because no aggregator-specific code path runs on a zero-step candidate —
+        // this synthetic quote is never itself signed; see the module doc comment
+        // above for where execution actually happens for the route built from it.
+        provider: provider,
+        quoteId,
+        tool: provider,
+        toolName: provider,
+        fromAmount: amountIn,
+        fromAmountUsd,
+        approvalAddress: null,
+        executionDurationSeconds: 0,
+        steps: [],
+        // A direct crossing carries no aggregator, so there is no carrier fee to
+        // report. The omnibridge's own crossing fee is `omnibridgeFeeAmount`
+        // beside it, which the route surfaces separately.
+        fees: [],
+        originDeposit: {
+            ecosystem: 'evm',
+            to: '0x0000000000000000000000000000000000000000',
+            data: '0x',
+            value: 0n,
+            chainId: originChainId,
+            gasLimit: null,
+        },
+    };
+    return {
+        id: quoteId,
+        quote: syntheticQuote,
+        omnibridgeProvider: provider,
+        entryChainId,
+        originToken,
+        destinationToken,
+        deliveredAmount: delivered,
+        omnibridgeFeeAmount,
+        destinationUsdPrice,
+        // A same-chain crossing has no aggregator leg to solve backward, so it spends
+        // exactly what was typed — requested and spent are the same figure by
+        // construction, and the route reports nothing unspent.
+        requestedAmount: amountIn,
+    };
+};

package/dist/routing/carriers/ask-answer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * What answering one carrier's ask produces: a deliverable amount, or a
+ * refusal. Declared LOCALLY, rather than imported, so gibs's own carriers
+ * (`omnibridge.ts`, `pulsex.ts`) can pin their `ask` function's return type
+ * without `bridge-sdk` depending on `@gibs/quotes` — see
+ * `@gibs/quotes/types`'s own doc on why that dependency would be circular.
+ *
+ * STRUCTURALLY IDENTICAL to `@gibs/quotes`'s `CarrierAskAnswer` (itself an
+ * alias of `search/waves.ts`'s `AskEdgeAnswer`) — every field name and type
+ * matches exactly, which is what lets an object shaped like this satisfy
+ * `Carrier.ask`'s return type wherever a caller that imports both packages
+ * (`packages/ui`) assigns one of these carriers into a `Carrier[]` list. This
+ * file is the ONE place that shape is spelled out in `bridge-sdk`; every
+ * carrier factory here imports this type rather than re-declaring it.
+ */
+export type CarrierAskAnswer = {
+    readonly ok: true;
+    /** What the edge delivers for the asked input, in `edge.to`'s base units. */
+    readonly deliveredAmount: bigint;
+    /** The GUARANTEED delivered amount after slippage, when known; null when not. */
+    readonly minimumDeliveredAmount: bigint | null;
+    /** The carrier's own claimed execution duration in seconds, or null. */
+    readonly claimedDurationSeconds: number | null;
+} | {
+    readonly ok: false;
+    readonly refusal: {
+        readonly kind: 'no-quote' | 'could-not-ask' | 'cannot-carry' | 'below-minimum' | 'above-available';
+        /** The carrier's own words for why, or null when none was given. */
+        readonly reason: string | null;
+        /** A minimum amount this refusal names, in `edge.from`'s base units, or null. */
+        readonly minimumAmount: bigint | null;
+    };
+};
+/**
+ * What answering one carrier's SYNCHRONOUS, EXACT read produces for one edge
+ * at one input amount: a delivered amount, or a refusal. Declared LOCALLY for
+ * the same reason {@link CarrierAskAnswer} is — see that type's own doc.
+ *
+ * STRUCTURALLY IDENTICAL to `@gibs/quotes`'s `ExactHopResult`. `'refused'` is
+ * a REAL answer (the carrier's own local read says this amount cannot
+ * cross), distinct from the bare `null` a carrier's `exact` method may also
+ * return for an edge it has nothing to say about (its `prepare` was never
+ * called, or this edge fell outside what it read).
+ */
+export type CarrierExactResult = {
+    readonly outcome: 'delivered';
+    /** What this edge delivers for exactly the requested input amount, in `edge.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';
+    readonly refusal: {
+        readonly kind: 'no-quote' | 'could-not-ask' | 'cannot-carry' | 'below-minimum' | 'above-available';
+        /** The carrier's own words for why, or null when none was given. */
+        readonly reason: string | null;
+        /** A minimum amount this refusal names, in `edge.from`'s base units, or null. */
+        readonly minimumAmount: bigint | null;
+    };
+};

package/dist/routing/carriers/ask-answer.js

@@ -0,0 +1 @@
+export {};

package/dist/routing/carriers/omnibridge.d.ts

@@ -0,0 +1,137 @@
+import type { PublicClient } from 'viem';
+import { type EntryLimits } from '../../bridge-limits.js';
+import type { Token } from '../../types.js';
+import { type AssetNode, type HopEdge } from '../search/graph.js';
+import type { CarrierAskAnswer, CarrierExactResult } from './ask-answer.js';
+/**
+ * The omnibridge crossing (`'pulsechain'` — the Ethereum entry — and
+ * `'tokensex'` — the Binance Smart Chain entry) as a plug-in `Carrier` for
+ * `@gibs/quotes`'s route-search engine. GIBS-SPECIFIC — see
+ * `docs/quote-service.md`'s "Carriers" section: "never built in ... the
+ * omnibridge crossing." Registered from `packages/ui/src/lib/state/useRouteSearch.ts`
+ * / `route-search-quotes.ts`.
+ *
+ * This module returns a plain object shaped like `@gibs/quotes`'s `Carrier`
+ * type WITHOUT importing it — `bridge-sdk` cannot depend on `@gibs/quotes`
+ * (see `@gibs/quotes/types`'s own doc on the circular-dependency reason).
+ * `HopEdge`/`AssetNode`/`AskEdgeAnswer` here are the SAME declarations that
+ * package's `CarrierHopEdge`/`CarrierAssetNode`/`CarrierAskAnswer` alias, so
+ * the object is structurally identical to a `Carrier` wherever a caller that
+ * imports both packages assigns it into one.
+ */
+/**
+ * One token the omnibridge bridges between its entry chain (Ethereum or
+ * Binance Smart Chain today; a testnet entry chain under `testnetPathways`)
+ * and PulseChain.
+ *
+ * NAMED `entryChainToken`, NOT `ethereumToken`. The UI's own
+ * `ConsolidatedDestinationPair` (`packages/ui/src/lib/stores/consolidated-tokens.ts`)
+ * keeps the older name for its Ethereum-only history; this module reuses its
+ * shape, not its name, because a Binance Smart Chain pair routed through the
+ * same field would otherwise carry an Ethereum-shaped name for a token that
+ * never touches Ethereum.
+ */
+export type BridgeablePair = {
+    /** The token on the omnibridge's entry chain. */
+    readonly entryChainToken: Token;
+    /** That token's PulseChain-side representation. */
+    readonly pulsechainToken: Token;
+    /** The entry chain's decimal chain id — the chain `entryChainToken` lives on. */
+    readonly entryChainId: number;
+};
+/** What {@link createOmnibridgeCarrier} needs. */
+export type CreateOmnibridgeCarrierOptions = {
+    /** Every token pair the omnibridge bridges, entry chain by entry chain. */
+    readonly bridgeablePairs: readonly BridgeablePair[];
+    /** Whether this is a production build — see `pathway()`'s own `isProd`. */
+    readonly isProductionNetwork: boolean;
+    /** Reads the entry mediator's bounds for one bridge-crossing edge — a free, local read. */
+    readonly readEntryLimits: (edge: HopEdge) => Promise<EntryLimits | null>;
+    /** Reads the omnibridge's own fee rate (per ether) for one bridge-crossing edge, in whichever direction it runs. */
+    readonly readFeePerEther: (edge: HopEdge) => Promise<bigint | null>;
+    /**
+     * Returns a client for a chain id, for {@link Carrier.prepare}'s own
+     * batched multicall reads — never called by `ask`, which keeps using
+     * {@link readEntryLimits}/{@link readFeePerEther} unchanged.
+     *
+     * OPTIONAL, ON PURPOSE. A host that has not wired a client lookup yet gets
+     * the carrier's original behavior: `prepare` is a no-op and `exact` always
+     * returns `null`, so `enumerate.ts` falls through to `estimate`/the
+     * price-feed default exactly as it did before either method existed.
+     *
+     * @param chainId - the chain a batched read needs a client for
+     * @returns a client, or null when this host has none for that chain
+     */
+    readonly clientForChain?: (chainId: number) => PublicClient | null;
+};
+/**
+ * Builds the omnibridge crossing as a plug-in carrier.
+ *
+ * @param options - see {@link CreateOmnibridgeCarrierOptions}
+ * @returns the carrier — `id: 'omnibridge'`; every EDGE it offers carries the
+ *   real `'pulsechain'`/`'tokensex'` provider id, since one registration can
+ *   speak for either entry chain depending on the pair
+ */
+export declare const createOmnibridgeCarrier: (options: CreateOmnibridgeCarrierOptions) => {
+    id: string;
+    edgesFrom: (from: AssetNode, to: AssetNode) => readonly HopEdge[];
+    ask: ({ edge, inputAmount }: {
+        edge: HopEdge;
+        inputAmount: bigint;
+    }) => Promise<CarrierAskAnswer>;
+    prepare: (nodes: readonly AssetNode[]) => Promise<void>;
+    exact: (edge: HopEdge, amountIn: bigint) => CarrierExactResult | null;
+    isRateLimited: boolean;
+    depositMode: "wallet-signed";
+    sender: "omnibridge";
+    settlementSeconds: number;
+};
+/** What {@link withOmnibridgeEntryFusing}'s `fusesWithNext` is asked — structurally `@gibs/quotes`'s `CarrierFusesWithNextOptions`. */
+export type OmnibridgeFuseQuestion = {
+    /** What the acting (provider) hop spends. */
+    readonly hopFrom: AssetNode;
+    /** The carrier of the hop that follows. */
+    readonly nextHopCarrier: string;
+    /** What the following hop spends — where the provider hop lands. */
+    readonly nextHopFrom: AssetNode;
+    /** Where the following hop delivers. */
+    readonly nextHopDestinationChainId: number;
+};
+/**
+ * Wraps ANY carrier-shaped object (built-in or a host's own) with the
+ * omnibridge's OWN fuse rule: whether THIS carrier's execution, landing on
+ * arrival, also performs the omnibridge's entry call — so the two hops
+ * together cost the reader one signature instead of two.
+ *
+ * EVERY CONDITION IS A FACT THE PROVIDER'S OWN DESCRIPTOR STATES
+ * (`../../providers.ts`), never a name compared here:
+ *
+ * - it executes destination calls at all (`executesDestinationCalls` — true
+ *   for LI.FI and Relay, false for NEAR Intents, which delivers to the
+ *   reader's own wallet and stops);
+ * - it can do so FROM this hop's origin chain (`destinationCallOriginChainIds`
+ *   — LI.FI's contract-calls endpoint is Ethereum only, so from Base or
+ *   Arbitrum a LI.FI hop is an unfused delivery followed by a crossing the
+ *   reader signs);
+ * - when the entry is the omnibridge's NATIVE one (the provider lands a
+ *   native coin, and `wrapAndRelayTokens` is payable), it can attach value to
+ *   the call (`destinationCallCarriesNativeValue`);
+ * - and the next hop really IS the omnibridge entry, landing on PulseChain
+ *   (`relayTokens`/`wrapAndRelayTokens` both MINT there; any other
+ *   destination is the omnibridge's OUTBOUND leg, which no arrival can make).
+ *
+ * THIS IS THE ONE PLACE `'pulsechain'`/`'tokensex'`/PulseChain'S CHAIN ID
+ * APPEAR IN A `fusesWithNext` CALLBACK — gibs's own registration
+ * (`packages/ui/src/lib/state/useRouteSearch.ts`) wraps `createLifiCarrier`/
+ * `createRelayCarrier` with this before registering them, so the generic
+ * search engine (`@gibs/quotes`'s `capabilities.ts`) never has to know what
+ * "the bridge" means.
+ *
+ * @param carrier - the carrier to wrap; its own shape is preserved, only `fusesWithNext` is added/replaced
+ * @returns the same carrier, with a `fusesWithNext` that recognizes the omnibridge entry call
+ */
+export declare const withOmnibridgeEntryFusing: <T extends {
+    readonly id: string;
+}>(carrier: T) => T & {
+    readonly fusesWithNext: (nextHop: OmnibridgeFuseQuestion) => boolean;
+};