@gibs/bridge-sdk 1.18.0 → 1.20.0

package/dist/near-intents-conformance.js

@@ -1,35 +1,4 @@
-/**
- * Does the live service still answer in the shape this repository parses?
- *
- * THIS EXISTS BECAUSE NEAR INTENTS HAS NO TEST NETWORK. The vendor states it
- * four times in its own current material, most plainly in its list of common
- * questions: "There is no testnet deployment and no plans for one. We
- * recommend testing on NEAR mainnet using separate dev/test NEAR accounts."
- * So there is no safe copy of the service to check an integration against, and
- * the only honest substitute is a priced request against production that
- * reserves nothing — a dry quote. See `docs/near-intents-capability-survey.md`.
- *
- * WHAT THIS CLOSES THAT THE FIXTURES CANNOT. `near-intents.test.ts` runs
- * against real captures taken on 2026-09-17. A capture is a photograph: it
- * proves the parser reads what the service sent that day, and it goes on
- * proving that forever, including after the service stops sending it. Every
- * parser here is tolerant by design — it returns null rather than throwing —
- * so a field that changes type does not break a test, it removes a provider
- * from the interface with no message anywhere. `amountOut` arriving as a
- * number instead of a string is the whole failure: 37 green tests, and NEAR
- * Intents silently never bids again.
- *
- * So these functions name every field the parsers actually depend on and
- * report what is missing, rather than returning a normalized value. Handed a
- * live response they answer "has production drifted away from the captures".
- * Handed a capture they answer "is this capture still a fair stand-in".
- *
- * They are deliberately NOT parsers. A parser answers "can I use this"; these
- * answer "is this what I was written against", which is a different question
- * and needs the failures enumerated rather than collapsed into a null.
- */
 import { chainIdByNearIntentsChain } from './near-intents.js';
-/** Which parser depends on a field, so a finding says what will break. */
 const describe = (value) => {
     if (value === undefined) {
         return 'absent';
@@ -45,13 +14,6 @@ const describe = (value) => {
 const asRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
     ? value
     : null;
-/**
- * Checks one field and returns a finding when it is not the required type.
- *
- * A base-unit amount must be a NON-EMPTY string, because that is what
- * `parseAmount` in `near-intents.ts` requires: it refuses an empty string and
- * refuses a number, so either one silently collapses the whole quote to null.
- */
 const requireField = ({ container, key, path, kind, }) => {
     const value = container[key];
     if (kind === 'amount') {
@@ -73,21 +35,6 @@ const requireField = ({ container, key, path, kind, }) => {
         : { path, expected: 'a non-empty string', found: describe(value) };
 };
 const compact = (findings) => findings.filter((finding) => finding !== null);
-/**
- * Checks a `POST /v0/quote` answer against everything the quote parsers read.
- *
- * THE DOLLAR FIGURES ARE CHECKED THOUGH THE PARSER TOLERATES THEIR ABSENCE.
- * `parseNearIntentsQuote` turns a missing `amountInUsd` into null and carries
- * on, which is right for a quote and wrong for a conformance check: losing the
- * dollar figure leaves the reader a route with no price beside it, and nothing
- * else in the system would report that the service stopped sending one.
- *
- * @param payload - the raw JSON body the service answered with
- * @param options.expectDepositAddress - true for an executable (`dry: false`)
- *   answer, false for a dry one. A dry answer omits the deposit address by
- *   design, so requiring it there would report a finding on a healthy service
- * @returns every departure from the expected shape; empty means conformant
- */
 export const nearIntentsQuoteShapeFindings = (payload, { expectDepositAddress }) => {
     const body = asRecord(payload);
     if (!body) {
@@ -141,17 +88,6 @@ export const nearIntentsQuoteShapeFindings = (payload, { expectDepositAddress })
     ]);
     return [...findings, ...nearIntentsAppFeeFindings(body.quoteRequest)];
 };
-/**
- * Checks the echoed request for the surcharge a key-less caller is charged.
- *
- * THE SERVICE INSERTS THIS, NOT US. Nothing in this repository asks for an
- * `appFees` entry, and the fee parser only finds the twenty-five-basis-point
- * charge because the service writes it into the request it echoes back. If it
- * ever stops echoing it, the charge does not stop — it disappears from the
- * fee rows and the reader is shown a route that costs a quarter of a percent
- * more than the interface says. That is a silent understatement of cost, so it
- * is a finding rather than a tolerated absence.
- */
 const nearIntentsAppFeeFindings = (quoteRequest) => {
     const request = asRecord(quoteRequest);
     if (!request) {
@@ -189,23 +125,6 @@ const nearIntentsAppFeeFindings = (quoteRequest) => {
         });
     }));
 };
-/**
- * Checks a `GET /v0/tokens` answer, including the chain names we map by hand.
- *
- * AN UNMAPPED CHAIN NAME IS THE DRIFT MOST LIKELY TO HAPPEN AND LEAST LIKELY
- * TO BE NOTICED. `chainIdByNearIntentsChain` is a hand-written table, and
- * `findNearIntentsAsset` matches through it — so if the service renames a
- * chain or adds one, every asset on that chain becomes invisible to this
- * repository while the asset list parses perfectly and every test stays green.
- * The names are reported rather than the assets, because a new chain we do not
- * carry is ordinary and a renamed chain we DO carry is the emergency.
- *
- * @param payload - the raw JSON body from the asset endpoint
- * @param options.requiredChains - the service's own names for the chains this
- *   repository must keep reaching. A name missing from the answer means the
- *   service renamed or dropped it
- * @returns every departure from the expected shape; empty means conformant
- */
 export const nearIntentsTokenListShapeFindings = (payload, { requiredChains }) => {
     if (!Array.isArray(payload)) {
         return [{ path: '', expected: 'an array of assets', found: describe(payload) }];
@@ -259,26 +178,9 @@ export const nearIntentsTokenListShapeFindings = (payload, { requiredChains }) =
     }
     return findings;
 };
-/**
- * The service's own names for every chain this repository maps to a chain
- * identifier, which is exactly the set whose renaming would be invisible.
- */
 export const nearIntentsMappedChainNames = () => [
     ...chainIdByNearIntentsChain.keys(),
 ];
-/**
- * Checks a `GET /v0/status` answer against what the status parser reads.
- *
- * THE DELIVERY HASH IS NOT REQUIRED, and that is not laxity. A route awaiting
- * its deposit has genuinely not produced one, and the captured
- * `status-pending-deposit.json` is exactly that case — so requiring it would
- * report a finding on a perfectly healthy in-flight transfer. What is required
- * is that the ARRAY exists, because its absence is the difference between "no
- * hash yet" and "the service stopped telling us where the funds landed".
- *
- * @param payload - the raw JSON body from the status endpoint
- * @returns every departure from the expected shape; empty means conformant
- */
 export const nearIntentsStatusShapeFindings = (payload) => {
     const body = asRecord(payload);
     if (!body) {
@@ -306,18 +208,6 @@ export const nearIntentsStatusShapeFindings = (payload) => {
         ]),
     ];
 };
-/**
- * Checks a refusal body carries the message the refusal parser reads.
- *
- * BOTH SIZE FLOORS ARRIVE ONLY AS PROSE IN THIS FIELD. There is no code, no
- * limits endpoint and no structured figure — `parseNearIntentsQuoteRefusal`
- * runs a regular expression over the sentence. So if the wording changes, a
- * refusal that should withdraw the route from the competition instead reads as
- * `other`, and the reader waits for a bid that will never come.
- *
- * @param payload - the raw JSON body of a refused quote
- * @returns every departure from the expected shape; empty means conformant
- */
 export const nearIntentsRefusalShapeFindings = (payload) => {
     const body = asRecord(payload);
     if (!body) {

package/dist/near-intents-route.d.ts

@@ -1,5 +1,18 @@
 import type { DeferredCrossing, RouteCandidate } from './routing/candidate.js';
 import type { RouteData } from './routing/route-data.js';
+/**
+ * The name of a step that starts on one chain and ends on another (or the same).
+ *
+ * A step whose two chains differ is "Send to {end chain}". A step that never
+ * leaves its chain is a swap, so it is "Swap on {chain}". "Send to Ethereum"
+ * on a swap that starts and ends on Ethereum names a crossing that never
+ * happens.
+ *
+ * @param startChainId - the chain the step starts on
+ * @param endChainId - the chain the step ends on
+ * @returns the step's English label
+ */
+export declare const sendOrSwapLabel: (startChainId: number, endChainId: number) => string;
 /**
  * Builds the two-signature route for a candidate whose aggregator cannot
  * execute the omnibridge entry call.

package/dist/near-intents-route.js

@@ -3,63 +3,17 @@ import { BRIDGE_SETTLEMENT_ETA_MINUTES, providerDisplayName, pulsechainChainId,
 import { providerById } from './providers.js';
 import { usdValueOfAmount } from './routing/usd-value.js';
 import { chainDisplayName } from './chain-names.js';
-/**
- * The route shape for an aggregator that cannot execute on the chain it
- * delivers to.
- *
- * WHY THIS EXISTS AT ALL. Every other consolidated route in this repository is
- * ONE signature: the aggregator carries the reader's funds to an omnibridge
- * entry chain and its executor performs the entry call on arrival, so the
- * crossing into PulseChain happens inside the same transaction the reader
- * already signed. NEAR Intents cannot do that — it delivers tokens to an
- * address and runs nothing — and no arrangement of recipients works around it,
- * because every omnibridge entry point learns who the reader is from a data
- * field and a plain token transfer has none. See the head of `near-intents.ts`.
- *
- * So the crossing becomes TWO signatures, and the honest thing is to draw it
- * that way. The aggregator lands the anchor token in the reader's OWN wallet on
- * the entry chain; the reader then signs the ordinary omnibridge call
- * themselves. The interface already renders exactly this shape — a section
- * marked `deferred` draws "You sign this later" on the route itself rather than
- * hiding the fact in a tooltip — so nothing new had to be invented to show it.
- *
- * WHAT THIS MUST NEVER DO is present the second signature as optional, or let
- * the route claim a delivered amount as though it were settled. The reader is
- * mid-journey until they sign again, and a route that implies otherwise is
- * selling a single-signature experience it does not deliver.
- */
-/**
- * Turns a token into the display node the route strip draws, resolving its logo
- * here rather than in the view.
- *
- * Pre-resolved deliberately: a view-layer image fallback reaches only the nodes
- * a builder left unset, so a builder that sets the field and a builder that
- * does not produce different pictures for the same token.
- *
- * The chain badge goes through `networkOrPseudo`, not `network` — a deposit-
- * address origin (Zcash) carries a local, invented chain id the numeric
- * endpoint 404s on. See that helper's own note for why this lives in
- * `image-links.ts` rather than the richer client-side resolver.
- */
 const tokenNode = (token, chainId) => ({
     symbol: token.symbol,
     address: token.address,
     chainId,
     decimals: token.decimals,
-    // `tokenImageOrChainFallback`, NOT `image` — the ANCHOR node this call also
-    // draws can reach here before its exact address is known (the deferred
-    // crossing has not settled yet), and `image` either throws on an address it
-    // cannot checksum or draws nothing at all. See that helper's own note.
     logoUri: imageLinks.tokenImageOrChainFallback(token),
     chainLogoUri: imageLinks.networkOrPseudo(chainId),
 });
-/**
- * Parses one of the aggregator's own dollar figures.
- *
- * They arrive as decimal strings. A figure that will not parse becomes null
- * rather than zero, because zero is a real value that reads as "this leg is
- * free" — which is the one thing a cost figure must never say by accident.
- */
+export const sendOrSwapLabel = (startChainId, endChainId) => startChainId === endChainId
+    ? `Swap on ${chainDisplayName(endChainId)}`
+    : `Send to ${chainDisplayName(endChainId)}`;
 const usdNumber = (value) => {
     if (typeof value !== 'string' || value === '') {
         return null;
@@ -67,41 +21,11 @@ const usdNumber = (value) => {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : null;
 };
-/**
- * Builds the two-signature route for a candidate whose aggregator cannot
- * execute the omnibridge entry call.
- *
- * The result has exactly two sections, and the order carries the meaning:
- *
- *   1. The aggregator's leg, signed NOW. It ends with the anchor token sitting
- *      in the reader's own wallet on the entry chain.
- *   2. The omnibridge crossing, marked `deferred`, signed LATER by the reader.
- *
- * COSTS ARE SPLIT BETWEEN THE SECTIONS RATHER THAN POOLED, because a reader
- * deciding whether to accept a second signature needs to know what each half
- * costs. The first section's spread is the difference between the aggregator's
- * own paid and delivered figures — both from the one answer that priced them,
- * never from two feeds. The second section's cost is the omnibridge crossing
- * fee, computed from the known on-chain rate.
- *
- * THE DELIVERED FIGURE IS AN ESTIMATE AND THE INTERFACE KNOWS IT. A route whose
- * last section is deferred has not been quoted end to end, so
- * `outputAmountIsUnsettled` blanks the received-amount field on the reader's
- * behalf. The figure is still carried — the conversion route sets its estimate
- * the same way — so the route can be ranked and compared.
- *
- * @param candidate - the route candidate, which must carry a `deferredCrossing`
- * @returns the two-section route, or null when the candidate names no deferred
- *   crossing or no omnibridge provider to perform it
- */
 export const buildNearIntentsTwoStepRouteData = (candidate) => {
     const deferredCrossing = candidate.deferredCrossing;
     if (!deferredCrossing) {
         return null;
     }
-    // No omnibridge leg means there is no second signature, which means this is
-    // not the shape being built. A route the aggregator carries end to end is an
-    // ordinary one-signature route and belongs to `buildCandidateRouteData`.
     const omnibridgeProviderKey = candidate.omnibridgeProvider;
     if (omnibridgeProviderKey === null) {
         return null;
@@ -113,9 +37,6 @@ export const buildNearIntentsTwoStepRouteData = (candidate) => {
     const destinationNode = tokenNode(destinationToken, pulsechainChainId);
     const paidUsd = usdNumber(candidate.quote.fromAmountUsd);
     const landedUsd = usdNumber(anchorUsdValue);
-    // The aggregator's spread on its own leg: what the reader paid, less what the
-    // aggregator says arrives. Both figures come from the same answer, so the
-    // difference is the route and nothing else.
     const aggregatorFeeUsd = subtractUsdValues(paidUsd, landedUsd);
     const crossingFeeUsd = usdValueOfAmount({
         balance: candidate.omnibridgeFeeAmount,
@@ -127,35 +48,20 @@ export const buildNearIntentsTwoStepRouteData = (candidate) => {
         ? Math.ceil(candidate.quote.executionDurationSeconds / 60)
         : null;
     const aggregatorHop = {
-        // THIS HOP IS THE AGGREGATOR, NOT THE OMNIBRIDGE — `providerDisplayName`
-        // (used for the crossing hop below) is keyed only on `Providers.PULSECHAIN`
-        // / `Providers.TOKENSEX` and falls back to the generic "Omnibridge" for
-        // anything else. Run through it here, `candidate.quote.provider` (a
-        // `ProviderId` — 'lifi' | 'relay' | 'near-intents') had no entry, so a
-        // NEAR Intents two-step route named its first leg "Omnibridge" — the
-        // bridge, not the aggregator that actually carried it. `providerById` is
-        // total over `ProviderId` and throws on an unregistered one rather than
-        // silently naming a different provider.
         providerName: providerById(candidate.quote.provider).label,
         providerKey: candidate.quote.provider,
-        title: `Send to ${chainDisplayName(candidate.entryChainId)}`,
+        title: sendOrSwapLabel(originToken.chainId, candidate.entryChainId),
         conversion: `→ ${anchorToken.symbol}`,
         fromToken: originNode,
         toToken: anchorNode,
         feeUsdValue: aggregatorFeeUsd,
-        // The reader's own signature starts this leg; nothing runs inside it.
         automatic: false,
     };
     const aggregatorSection = {
         id: `${candidate.id}-signature-1`,
-        // Named for where the funds END UP, and pointedly NOT "Bridge to
-        // PulseChain": this signature does not reach PulseChain and a label that
-        // said so would be the single-signature claim this route exists to avoid.
-        label: `Send to ${chainDisplayName(candidate.entryChainId)}`,
+        label: sendOrSwapLabel(originToken.chainId, candidate.entryChainId),
         providerKey: candidate.quote.provider,
         tokenFlow: [originNode, anchorNode],
-        // WHAT THE READER IS LEFT HOLDING between the two signatures, in their own
-        // wallet on the entry chain. This is the step's whole point.
         landing: {
             amount: anchorAmount,
             decimals: anchorToken.decimals,
@@ -176,9 +82,6 @@ export const buildNearIntentsTwoStepRouteData = (candidate) => {
         fromToken: anchorNode,
         toToken: destinationNode,
         feeUsdValue: crossingFeeUsd,
-        // NOT automatic, and this is the difference the whole route turns on. On a
-        // one-signature route the aggregator's executor makes this call; here the
-        // reader does, by hand, after the anchor lands.
         automatic: false,
     };
     const crossingSection = {
@@ -193,23 +96,8 @@ export const buildNearIntentsTwoStepRouteData = (candidate) => {
             usdValue: subtractUsdValues(landedUsd, crossingFeeUsd),
         },
         feeUsdValue: crossingFeeUsd,
-        // THE FLAG THAT MAKES THE ROUTE HONEST. It is what draws "You sign this
-        // later" on the step, what makes the primary button name the step it
-        // actually signs, and what stops any surface stating the delivered amount
-        // as settled. Removing it would turn this into a route that silently
-        // promises one signature and asks for two.
         deferred: true,
-        // `sectionDescription` in the route strip reads `section.deferredNote ??
-        // defaultDeferredNote()`, so a note supplied HERE replaces the default
-        // sentence outright rather than adding to it. The default sentence is
-        // "Fee is approximate — quoted when you return." — the one fact that
-        // tells the reader the output figure they are looking at is not settled.
-        // A note that names only the second signature and drops that fact leaves
-        // a settled-looking figure on screen with nothing anywhere saying
-        // otherwise, so this note must carry BOTH facts itself.
         deferredNote: `The bridge crossing is a second signature you make once the funds arrive on ${chainDisplayName(candidate.entryChainId)}. The amount shown is approximate and is quoted again when you return.`,
-        // The crossing's own settlement wait, which is the long part of the journey
-        // and has nothing to do with the aggregator's estimate above.
         etaMinutes: BRIDGE_SETTLEMENT_ETA_MINUTES,
         hops: [crossingHop],
     };
@@ -219,41 +107,19 @@ export const buildNearIntentsTwoStepRouteData = (candidate) => {
     return {
         kind: 'aggregated',
         entryChainId: candidate.entryChainId,
-        // Named after the omnibridge, matching the one-signature route: a route is
-        // named for the thing that performs its defining leg.
         headlineProviderKey: omnibridgeProviderKey,
         sections: [aggregatorSection, crossingSection],
         output: {
             amount: candidate.deliveredAmount,
             decimals: destinationToken.decimals,
             symbol: destinationToken.symbol,
-            // The source basis, carried the whole way: what was paid, less what each
-            // leg costs. Re-pricing the delivered token against its own feed would
-            // state this route's cost twice and the two would not agree.
             usdValue: subtractUsdValues(paidUsd, totalCostUsdValue),
         },
         totalCostUsdValue,
-        // Ranked on the same net figure as every other route: delivered value less
-        // everything the journey costs.
         netValueUsd: subtractUsdValues(paidUsd, totalCostUsdValue),
-        // The reader's wait is BOTH legs, not the aggregator's leg alone. A route
-        // that reported only the first would claim to finish before its second
-        // signature had even been asked for.
         etaMinutes: (etaMinutes ?? 0) + BRIDGE_SETTLEMENT_ETA_MINUTES,
     };
 };
-/**
- * Describes the anchor a two-signature route leaves the reader holding.
- *
- * A small constructor rather than an inline object literal at the call site,
- * so the three fields are named and documented in one place and a caller
- * cannot quietly pair one aggregator's amount with another's valuation.
- *
- * @param options.anchorToken - the entry-chain token the aggregator delivers
- * @param options.anchorAmount - how much of it lands, in its base units
- * @param options.anchorUsdValue - the AGGREGATOR'S own valuation of that landing
- * @returns the deferred-crossing record, or null when no amount is known
- */
 export const describeDeferredCrossing = ({ anchorToken, anchorAmount, anchorUsdValue, }) => {
     if (anchorToken === null) {
         return null;