@gibs/bridge-sdk 1.13.0 → 1.13.1

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

@@ -46,6 +46,8 @@ 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: {

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

@@ -55,6 +55,44 @@ export declare const pulseXRouterForEdge: (edge: Pick<HopEdge, "carrier" | "venu
  * @returns the swap path, or null when there is nothing for PulseX to swap
  */
 export declare const pulseXPoolPath: (from: AssetNode, to: AssetNode) => readonly Hex[] | null;
+/** One pool a swap path crosses, read in the direction of travel. */
+export type PulseXPathStep = {
+    /** The pool's reserve of the token flowing in. */
+    readonly reserveIn: bigint;
+    /** The pool's reserve of the token flowing out. */
+    readonly reserveOut: bigint;
+};
+/**
+ * What `amountIn` delivers after crossing every pool of a path in order,
+ * chaining {@link constantProductAmountOut}.
+ *
+ * @param amountIn - the amount entering the first pool
+ * @param steps - the pools in order of travel
+ * @returns the amount leaving the last pool; 0 when any pool cannot pay out
+ */
+export declare const amountOutAlongPath: (amountIn: bigint, steps: readonly PulseXPathStep[]) => bigint;
+/**
+ * How far a trade's executed rate falls below the marginal (near-spot) rate,
+ * in percent. The marginal rate is a tiny reference trade through the same
+ * pools (`amountIn / PULSEX_MARGINAL_REFERENCE_DIVISOR`). The swap fee rides
+ * in both rates, so it cancels and the gap is price impact alone. A path
+ * through several pools composes by itself: the reference trade crosses the
+ * same pools in the same order.
+ *
+ *   impact = (1 - (amountOut / amountIn) / (referenceAmountOut / referenceAmountIn)) * 100
+ *
+ * @param options.amountIn - the full trade's input
+ * @param options.amountOut - what the full trade delivers
+ * @param options.referenceAmountIn - the reference trade's input
+ * @param options.referenceAmountOut - what the reference trade delivers
+ * @returns the impact in percent, never below 0; null when a reference figure is zero (impact cannot be measured)
+ */
+export declare const priceImpactAgainstMarginal: (options: {
+    readonly amountIn: bigint;
+    readonly amountOut: bigint;
+    readonly referenceAmountIn: bigint;
+    readonly referenceAmountOut: bigint;
+}) => number | null;
 /** What {@link createPulseXCarrier} needs. */
 export type CreatePulseXCarrierOptions = {
     /**

package/dist/routing/carriers/pulsex.js

@@ -5,7 +5,7 @@ import { chainsMetadata } from '../../chains.js';
 import { Chains, nativeAssetOut, toChain, uniV2Factories, uniV2Routers } from '../../config.js';
 import { sameAddress } from '../../ecosystems.js';
 import { pulseXConversionSwapPath } from '../providers.js';
-import { pulsechainChainId } from '../producers.js';
+import { PULSEX_MARGINAL_REFERENCE_DIVISOR, pulsechainChainId } from '../producers.js';
 import { assetNodeKey } from '../search/graph.js';
 /**
  * PulseX (the PulseChain-native decentralized exchange, used here for a
@@ -172,6 +172,44 @@ const constantProductAmountOut = (amountIn, reserveIn, reserveOut) => {
     const denominator = reserveIn * PULSEX_FEE_DENOMINATOR + amountInWithFee;
     return numerator / denominator;
 };
+/**
+ * What `amountIn` delivers after crossing every pool of a path in order,
+ * chaining {@link constantProductAmountOut}.
+ *
+ * @param amountIn - the amount entering the first pool
+ * @param steps - the pools in order of travel
+ * @returns the amount leaving the last pool; 0 when any pool cannot pay out
+ */
+export const amountOutAlongPath = (amountIn, steps) => steps.reduce((runningAmount, step) => constantProductAmountOut(runningAmount, step.reserveIn, step.reserveOut), amountIn);
+/**
+ * How far a trade's executed rate falls below the marginal (near-spot) rate,
+ * in percent. The marginal rate is a tiny reference trade through the same
+ * pools (`amountIn / PULSEX_MARGINAL_REFERENCE_DIVISOR`). The swap fee rides
+ * in both rates, so it cancels and the gap is price impact alone. A path
+ * through several pools composes by itself: the reference trade crosses the
+ * same pools in the same order.
+ *
+ *   impact = (1 - (amountOut / amountIn) / (referenceAmountOut / referenceAmountIn)) * 100
+ *
+ * @param options.amountIn - the full trade's input
+ * @param options.amountOut - what the full trade delivers
+ * @param options.referenceAmountIn - the reference trade's input
+ * @param options.referenceAmountOut - what the reference trade delivers
+ * @returns the impact in percent, never below 0; null when a reference figure is zero (impact cannot be measured)
+ */
+export const priceImpactAgainstMarginal = (options) => {
+    const { amountIn, amountOut, referenceAmountIn, referenceAmountOut } = options;
+    if (amountIn <= 0n || referenceAmountIn <= 0n || referenceAmountOut <= 0n)
+        return null;
+    // The output the trade would deliver at the marginal rate with no impact.
+    const idealAmountOut = (referenceAmountOut * amountIn) / referenceAmountIn;
+    if (idealAmountOut <= 0n)
+        return null;
+    if (amountOut >= idealAmountOut)
+        return 0;
+    const MILLIONTHS = 1000000n;
+    return Number(((idealAmountOut - amountOut) * MILLIONTHS * 100n) / idealAmountOut) / Number(MILLIONTHS);
+};
 /** The stable key one pool is stored and looked up under — the two token addresses, lower-cased and sorted, so either query order finds the same entry. */
 const poolKey = (tokenA, tokenB) => {
     const [lower, higher] = [tokenA.toLowerCase(), tokenB.toLowerCase()].sort();
@@ -365,7 +403,7 @@ export const createPulseXCarrier = (options) => {
         const hops = hopsAlongPath(path);
         if (hops.length === 0)
             return null;
-        let runningAmount = amountIn;
+        const steps = [];
         for (const [tokenIn, tokenOut] of hops) {
             const reserves = reservesByPoolKey.get(venuePoolKey(venue, tokenIn, tokenOut));
             // `prepare` never read this pool — a structural non-answer, not a
@@ -377,15 +415,26 @@ export const createPulseXCarrier = (options) => {
             if (reserves === undefined)
                 return null;
             const tokenInIsLower = tokenIn.toLowerCase() < tokenOut.toLowerCase();
-            const reserveIn = tokenInIsLower ? reserves.reserveOfLowerAddress : reserves.reserveOfHigherAddress;
-            const reserveOut = tokenInIsLower ? reserves.reserveOfHigherAddress : reserves.reserveOfLowerAddress;
-            const hopAmountOut = constantProductAmountOut(runningAmount, reserveIn, reserveOut);
-            if (hopAmountOut <= 0n) {
-                return { outcome: 'refused', refusal: { kind: 'no-quote', reason: 'no liquidity on this PulseX path', minimumAmount: null } };
-            }
-            runningAmount = hopAmountOut;
+            steps.push({
+                reserveIn: tokenInIsLower ? reserves.reserveOfLowerAddress : reserves.reserveOfHigherAddress,
+                reserveOut: tokenInIsLower ? reserves.reserveOfHigherAddress : reserves.reserveOfLowerAddress,
+            });
+        }
+        const deliveredAmount = amountOutAlongPath(amountIn, steps);
+        if (deliveredAmount <= 0n) {
+            return { outcome: 'refused', refusal: { kind: 'no-quote', reason: 'no liquidity on this PulseX path', minimumAmount: null } };
         }
-        return { outcome: 'delivered', deliveredAmount: runningAmount };
+        const priceImpactPercent = priceImpactAgainstMarginal({
+            amountIn,
+            amountOut: deliveredAmount,
+            referenceAmountIn: amountIn / PULSEX_MARGINAL_REFERENCE_DIVISOR,
+            referenceAmountOut: amountOutAlongPath(amountIn / PULSEX_MARGINAL_REFERENCE_DIVISOR, steps),
+        });
+        // Left off (not zero) when the reference trade rounds away: an unknown
+        // impact must stay unknown so the quality gate withholds the plan.
+        return priceImpactPercent === null
+            ? { outcome: 'delivered', deliveredAmount }
+            : { outcome: 'delivered', deliveredAmount, priceImpactPercent };
     };
     return {
         id: 'PulseX',

package/dist/routing/index.d.ts

@@ -22,7 +22,7 @@ export { RANKABLE_ESTIMATE_BASES, assetNodeKey, combineComposedPathBasis, compar
 export type { AssetNode, CarrierId, ComposedPathBasis, HopCarrier, HopEdge, HopEdgeOrigin, HopFloor, HopOutcome, HopRequest, PlannedHop, RoutePlan, } from './search/graph.js';
 export { composableHopBasis, composeRouteDelivery, hopOutputAmount, } from './search/compose.js';
 export type { ComposableHop, ComposableHopFigure, ComposeRefusalReason, ComposedRouteDelivery, ExchangeRate, } from './search/compose.js';
-export { GAS_TOPUP_PENALTY_FLOOR_USD, GAS_TOPUP_PENALTY_PPM, SIGNATURE_PENALTY_FLOOR_USD, SIGNATURE_PENALTY_PPM, compareRoutePlansByGasAdjustedDeliveredAmount, compareRoutePlansByScoreAdjustedDeliveredAmount, gasAdjustedDeliveredAmount, scoreRoutePlan, waitPenaltyPpm, zeroGasCostFor, } from './search/score.js';
+export { GAS_TOPUP_PENALTY_FLOOR_USD, GAS_TOPUP_PENALTY_PPM, SIGNATURE_PENALTY_FLOOR_USD, SIGNATURE_PENALTY_PPM, compareRoutePlansByGasAdjustedDeliveredAmount, compareRoutePlansByScoreAdjustedDeliveredAmount, gasAdjustedDeliveredAmount, scoreRoutePlan, sectionIsFundedByLanding, waitPenaltyPpm, zeroGasCostFor, } from './search/score.js';
 export type { GasCostFor, GasCostQuote, RouteScoreInputs } from './search/score.js';
 export { buildRouteCandidateFromPlan, buildRouteDataFromPlan, buildRouteScoreInputsFromPlan, deriveDeferredCrossingFromPlan, deriveEntryChainIdFromPlan, deriveOmnibridgeProviderFromPlan, deriveViaChainIdsFromPlan, derivePlanKind, } from './search/plan-route-data.js';
 export type { PlanCandidateInputs, PlanRouteDataInputs, PlanSectionPricing, PlanValuation, ResolveNodeToken, } from './search/plan-route-data.js';

package/dist/routing/index.js

@@ -25,7 +25,7 @@ export { BRIDGE_SETTLEMENT_ETA_MINUTES, PULSEX_MARGINAL_REFERENCE_DIVISOR, pulse
 // under its `Carrier*` names.
 export { RANKABLE_ESTIMATE_BASES, assetNodeKey, combineComposedPathBasis, compareRoutePlansByDeliveredAmount, groupHopsBySignature, hopComposedBasis, hopEdgeKey, isConfirmedBasis, isRankableBasis, isRateLimitedCarrier, planComposedBasis, planIsConfirmed, planIsRankable, routePlanPathKey, } from './search/graph.js';
 export { composableHopBasis, composeRouteDelivery, hopOutputAmount, } from './search/compose.js';
-export { GAS_TOPUP_PENALTY_FLOOR_USD, GAS_TOPUP_PENALTY_PPM, SIGNATURE_PENALTY_FLOOR_USD, SIGNATURE_PENALTY_PPM, compareRoutePlansByGasAdjustedDeliveredAmount, compareRoutePlansByScoreAdjustedDeliveredAmount, gasAdjustedDeliveredAmount, scoreRoutePlan, waitPenaltyPpm, zeroGasCostFor, } from './search/score.js';
+export { GAS_TOPUP_PENALTY_FLOOR_USD, GAS_TOPUP_PENALTY_PPM, SIGNATURE_PENALTY_FLOOR_USD, SIGNATURE_PENALTY_PPM, compareRoutePlansByGasAdjustedDeliveredAmount, compareRoutePlansByScoreAdjustedDeliveredAmount, gasAdjustedDeliveredAmount, scoreRoutePlan, sectionIsFundedByLanding, waitPenaltyPpm, zeroGasCostFor, } from './search/score.js';
 // General route search — Phase 1: plan-route-data.ts. Turns a priced
 // RoutePlan into the same RouteData/RouteCandidate/RouteScoreInputs shapes
 // today's four hand-written producers emit — see that module's head doc.

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

@@ -318,6 +318,12 @@ export type HopOutcome = {
      * build exactly the request the route was priced for.
      */
     readonly minimumDeliveredAmount?: bigint;
+    /**
+     * How far the hop's executed rate falls below its marginal rate, in
+     * percent — present only when the carrier measured it from its own
+     * pool reserves (a PulseX swap). Absent means "not measured", never zero.
+     */
+    readonly priceImpactPercent?: number;
 } | {
     readonly kind: 'estimate';
     /** The composed/probed figure, in the hop's `to` node's base units. */
@@ -353,6 +359,14 @@ export type HopOutcome = {
      * a plan on any more.
      */
     readonly refusalReason?: string | null;
+    /**
+     * The price impact measured when the carrier answered this hop exactly,
+     * carried onto the rescaled estimate when an upstream amount moved and
+     * the exact figure no longer applies verbatim. Impact grows roughly in
+     * proportion to the trade, so the carried figure stays close for the
+     * small moves a live upstream quote makes. Absent means "not measured".
+     */
+    readonly priceImpactPercent?: number;
 };
 /**
  * Whether every hop of `hops` carries a figure a ranking may trust: a live

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

@@ -244,8 +244,20 @@ export type GasCostQuote = {
      * 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.
+     *
+     * A SECTION THE PREVIOUS SECTION FUNDS IS NEVER CHARGED THIS. When the
+     * hop landing on this chain delivers native coin, the reader arrives
+     * holding gas — {@link gasAdjustedDeliveredAmount} drops this figure for
+     * that section (see {@link sectionIsFundedByLanding}).
      */
     readonly refuelAmount: bigint;
+    /**
+     * The native coin this signature burns, in the signing chain's own native
+     * base units (wei on an Ethereum-Virtual-Machine chain) — the amount a gas
+     * top-up has to land at minimum. Optional: a caller with no gas-price read
+     * omits it, and a served top-up then reports its native amount as unknown.
+     */
+    readonly nativeGasAmount?: bigint;
 };
 /**
  * Supplies the REAL cost of signing one step, for the chain it broadcasts on
@@ -285,12 +297,29 @@ export type GasCostFor = (chainId: number, sender: HopCarrier) => GasCostQuote;
  * has something total to call when nobody has.
  */
 export declare const zeroGasCostFor: GasCostFor;
+/**
+ * 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
+ */
+export declare const sectionIsFundedByLanding: (plan: RoutePlan, sectionIndex: number) => boolean;
 /**
  * `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
+ * 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

package/dist/routing/search/score.js

@@ -1,3 +1,4 @@
+import { isNativeAsset } from '../../ecosystems.js';
 import { compareRoutePlansByDeliveredAmount, planIsRankable, isRankableBasis, } from './graph.js';
 /**
  * PHASE 0 — FOUNDATION ONLY. Today this module holds exactly one function,
@@ -337,12 +338,37 @@ export const scoreRoutePlan = (inputs) => {
  * has something total to call when nobody has.
  */
 export const zeroGasCostFor = () => ({ gasAmount: 0n, refuelAmount: 0n });
+/**
+ * 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
+ */
+export const sectionIsFundedByLanding = (plan, sectionIndex) => {
+    if (sectionIndex < 1)
+        return false;
+    const previousGroup = plan.signatures[sectionIndex - 1];
+    const landingHop = plan.hops[previousGroup?.[previousGroup.length - 1] ?? -1];
+    if (landingHop === undefined)
+        return false;
+    return isNativeAsset(landingHop.edge.to.address, landingHop.edge.to.ecosystem);
+};
 /**
  * `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
+ * 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
@@ -351,13 +377,14 @@ export const zeroGasCostFor = () => ({ gasAmount: 0n, refuelAmount: 0n });
  */
 export const gasAdjustedDeliveredAmount = (plan, gasCostFor) => {
     const deliveredAmount = plan.hops[plan.hops.length - 1]?.outcome.deliveredAmount ?? 0n;
-    const totalGasCost = plan.signatures.reduce((total, group) => {
+    const totalGasCost = plan.signatures.reduce((total, group, sectionIndex) => {
         const firstHopIndex = group[0];
         const firstHop = firstHopIndex === undefined ? undefined : plan.hops[firstHopIndex];
         if (firstHop === undefined)
             return total;
         const quote = gasCostFor(firstHop.edge.from.chainId, firstHop.edge.carrier);
-        return total + quote.gasAmount + quote.refuelAmount;
+        const refuelAmount = sectionIsFundedByLanding(plan, sectionIndex) ? 0n : quote.refuelAmount;
+        return total + quote.gasAmount + refuelAmount;
     }, 0n);
     const netAmount = deliveredAmount - totalGasCost;
     return netAmount < 0n ? 0n : netAmount;

package/llms.txt

@@ -0,0 +1,169 @@
+# @gibs/bridge-sdk
+
+> A TypeScript library that prices and builds transfers across the Gibs
+> Finance omnibridges (PulseChain with Ethereum, PulseChain with BNB Smart
+> Chain). It also builds the requests for the aggregator routes (LI.FI,
+> Relay, NEAR Intents) that reach those bridges from other chains. It does
+> not sign or send anything. You bring a viem client and a wallet.
+
+## Install
+
+- Run `npm install @gibs/bridge-sdk viem`.
+- The package is ESM only. Use `import`, not `require`.
+- It needs Node 20 or later (`engines.node` is `>=20`).
+- viem is a peer dependency. The range is `>=2.37.0 <3`.
+- Version note: 1.12.0 and older on npm are broken. 1.13.0 is the first usable version.
+- In a browser, `@gibs/bridge-sdk/ton-execution` needs a global `Buffer`. No other entry point does.
+
+## Entry points
+
+Import from the narrowest subpath. The root `@gibs/bridge-sdk` exports everything.
+
+- `@gibs/bridge-sdk/config`: chains, providers, pathways, native-asset tables.
+- `@gibs/bridge-sdk/types`: shared types such as `BridgeKey` and `Token`.
+- `@gibs/bridge-sdk/chains`: viem chain objects with logos and RPC URLs.
+- `@gibs/bridge-sdk/chain-info`: on-chain reads (token mappings, fees, minimum amounts).
+- `@gibs/bridge-sdk/settings`: fee and amount arithmetic.
+- `@gibs/bridge-sdk/consolidated-quote`: LI.FI request builders and parsers.
+- `@gibs/bridge-sdk/relay-quote`: Relay request builders and parsers.
+- `@gibs/bridge-sdk/near-intents`: NEAR Intents requests and parsers.
+- `@gibs/bridge-sdk/pre-quote`: price checks before a binding quote.
+- `@gibs/bridge-sdk/routing`: route search across carriers.
+- `@gibs/bridge-sdk/image-links`: image URLs from gib.show.
+- `@gibs/bridge-sdk/abis`: contract ABIs.
+
+## Chains and pathways
+
+A chain is a hex id from the `Chains` enum. A route is a `BridgeKey`:
+`[provider, fromChain, toChain]`. `pathway` returns the contract addresses
+for a key, or `undefined` when no pathway exists.
+
+```ts
+import { Chains, Providers, pathway } from '@gibs/bridge-sdk/config'
+import type { BridgeKey } from '@gibs/bridge-sdk/types'
+
+const bridgeKey: BridgeKey = [Providers.PULSECHAIN, Chains.ETH, Chains.PLS]
+const route = pathway(bridgeKey, true) // true: mainnet only
+if (route) {
+  route.from // the mediator on Ethereum, where funds enter
+  route.feeManager // 'to': the PulseChain mediator owns the fee manager
+}
+```
+
+## Fees: direction and units
+
+These rules must hold in every integration.
+
+- PulseChain is the home side of both omnibridges.
+- Foreign to home (`feeF2H`) means entering PulseChain.
+- Home to foreign (`feeH2F`) means leaving PulseChain.
+- Use the fee for your direction. Do not use one fee for both.
+- Bridge fees are a rate per `1e18`. `1e18` is one hundred percent.
+- Aggregator referral fees are basis points. `10_000n` is one hundred percent.
+- LI.FI takes its fee as a decimal fraction (`0.001` is a tenth of a percent).
+- Fees are on-chain settings. Read them. Do not hard-code them.
+
+```ts
+import { loadBridgeFees } from '@gibs/bridge-sdk/chain-info'
+import { Chains, pathway, Providers } from '@gibs/bridge-sdk/config'
+import { amountAfterBridgeFee, bridgeCost } from '@gibs/bridge-sdk/settings'
+import type { PublicClient } from 'viem'
+
+declare const ethereumClient: PublicClient
+declare const pulsechainClient: PublicClient
+
+const route = pathway([Providers.PULSECHAIN, Chains.ETH, Chains.PLS], true)
+if (route) {
+  const { feeF2H } = await loadBridgeFees({
+    pathway: route,
+    fromChainClient: ethereumClient,
+    toChainClient: pulsechainClient,
+  })
+  const amountToBridge = 1_000_000n
+  const cost = bridgeCost({ amountToBridge, bridgeFee: feeF2H })
+  const received = amountAfterBridgeFee({ amountToBridge, bridgeCost: cost })
+}
+```
+
+`loadBridgeFees` reads the default rate. It does not read per-token rates.
+
+## Tokens that are not bridged yet
+
+`tokenBridgeInfo` asks both mediators how a token maps across the bridge.
+A `null` `assetOutAddress` is a normal answer. The token gets an address on
+the far side when its first transfer arrives. Always check for `null`.
+
+```ts
+import { tokenBridgeInfo } from '@gibs/bridge-sdk/chain-info'
+import { Chains, Providers } from '@gibs/bridge-sdk/config'
+import type { Token } from '@gibs/bridge-sdk/types'
+import type { PublicClient } from 'viem'
+
+declare const assetIn: Token
+declare const ethereumClient: PublicClient
+declare const pulsechainClient: PublicClient
+
+const info = await tokenBridgeInfo({
+  bridgeKey: [Providers.PULSECHAIN, Chains.ETH, Chains.PLS],
+  assetIn,
+  isProd: true,
+  fromChainClient: ethereumClient,
+  toChainClient: pulsechainClient,
+})
+if (info && info.assetOutAddress === null) {
+  // Not bridged yet. Do not treat this as an error.
+}
+```
+
+## Aggregator identity: pass your own
+
+The package ships no API key. Pass your own.
+
+- Relay: pass your own `apiKey` to `relayRequestHeaders`. Name your own `relayReferrer`. The package sends no referrer by default, because Relay rejects a referrer without a key.
+- LI.FI: set your own `lifiIntegrator`. A positive `lifiFee` without your own integrator throws.
+- NEAR Intents: no key is needed. Pass your own `userAgent` if you want one.
+
+```ts
+import {
+  buildLifiContractCallsRequest,
+  type ConsolidatedQuoteRequest,
+} from '@gibs/bridge-sdk/consolidated-quote'
+import { nearIntentsRequestHeaders } from '@gibs/bridge-sdk/near-intents'
+import { buildRelayQuoteRequest, relayQuoteUrl, relayRequestHeaders } from '@gibs/bridge-sdk/relay-quote'
+
+declare const baseRequest: ConsolidatedQuoteRequest
+declare const myRelayApiKey: string
+
+const request: ConsolidatedQuoteRequest = {
+  ...baseRequest,
+  lifiIntegrator: 'your-app.example',
+  lifiFee: 0.001,
+  relayReferrer: 'your-app.example',
+}
+
+const lifiBody = buildLifiContractCallsRequest(request)
+const relayBody = buildRelayQuoteRequest(request)
+if (relayBody) {
+  await fetch(relayQuoteUrl, {
+    method: 'POST',
+    body: JSON.stringify(relayBody),
+    headers: relayRequestHeaders(myRelayApiKey),
+  })
+}
+
+const nearHeaders = nearIntentsRequestHeaders(undefined, { userAgent: 'your-app/1.0' })
+```
+
+## Nulls and throws
+
+- A question the package cannot answer returns `null`, `undefined` or `false`.
+- A caller mistake or a failed chain read throws.
+- Every request builder returns `null` for a request its provider cannot express.
+- Every response parser returns `null` for an unexpected response shape.
+- Check each return value before you use it.
+
+## Links
+
+- [README](https://github.com/gibsfinance/bridge/blob/staging/packages/bridge-sdk/README.md): the full guide.
+- [Gibs Finance llms.txt](https://next.gibs.finance/llms.txt): the whole platform.
+- [@gibs/quotes](https://github.com/gibsfinance/bridge/blob/staging/packages/quotes/llms.txt): live multi-provider quotes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gibs/bridge-sdk",
-  "version": "1.13.0",
+  "version": "1.13.1",
   "description": "Build and price cross-chain transfers between PulseChain, Ethereum, and Binance Smart Chain.",
   "keywords": [
     "ethereum",
@@ -185,7 +185,8 @@
     "!dist/tsconfig.tsbuildinfo",
     "!dist/**/*.test-d.*",
     "!dist/test-utils",
-    "LICENSE"
+    "LICENSE",
+    "llms.txt"
   ],
   "scripts": {
     "prepublishOnly": "npx tsc",
@@ -197,8 +198,8 @@
     "test:live:near-intents": "../../scripts/near-intents-live.sh"
   },
   "dependencies": {
-    "@gibs/abis": "^1.13.0",
-    "@gibs/common": "^1.13.0",
+    "@gibs/abis": "^1.13.1",
+    "@gibs/common": "^1.13.1",
     "@ton/core": "^0.63.1",
     "@ton/crypto": "^3.3.0",
     "lodash-es": "^4.17.21"