@gibs/bridge-sdk 1.13.0 → 1.17.0

package/dist/cjs/near-intents-route.js

@@ -0,0 +1,303 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeDeferredCrossing = exports.buildNearIntentsTwoStepRouteData = void 0;
+const imageLinks = __importStar(require("./image-links.js"));
+const producers_js_1 = require("./routing/producers.js");
+const providers_js_1 = require("./providers.js");
+const usd_value_js_1 = require("./routing/usd-value.js");
+const chain_names_js_1 = require("./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.
+ */
+const usdNumber = (value) => {
+    if (typeof value !== 'string' || value === '') {
+        return null;
+    }
+    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
+ */
+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;
+    }
+    const { originToken, destinationToken } = candidate;
+    const { anchorToken, anchorAmount, anchorUsdValue } = deferredCrossing;
+    const originNode = tokenNode(originToken, originToken.chainId);
+    const anchorNode = tokenNode(anchorToken, candidate.entryChainId);
+    const destinationNode = tokenNode(destinationToken, producers_js_1.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 = (0, producers_js_1.subtractUsdValues)(paidUsd, landedUsd);
+    const crossingFeeUsd = (0, usd_value_js_1.usdValueOfAmount)({
+        balance: candidate.omnibridgeFeeAmount,
+        decimals: destinationToken.decimals,
+        price: candidate.destinationUsdPrice,
+    });
+    const etaSeconds = candidate.quote.executionDurationSeconds > 0 ? candidate.quote.executionDurationSeconds : null;
+    const etaMinutes = candidate.quote.executionDurationSeconds > 0
+        ? 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: (0, providers_js_1.providerById)(candidate.quote.provider).label,
+        providerKey: candidate.quote.provider,
+        title: `Send to ${(0, chain_names_js_1.chainDisplayName)(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 ${(0, chain_names_js_1.chainDisplayName)(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,
+            symbol: anchorToken.symbol,
+            usdValue: landedUsd,
+        },
+        feeUsdValue: aggregatorFeeUsd,
+        fees: candidate.quote.fees,
+        etaMinutes,
+        etaSeconds,
+        hops: [aggregatorHop],
+    };
+    const crossingHop = {
+        providerName: (0, producers_js_1.providerDisplayName)(omnibridgeProviderKey),
+        providerKey: omnibridgeProviderKey,
+        title: `Bridge to ${(0, chain_names_js_1.chainDisplayName)(producers_js_1.pulsechainChainId)}`,
+        conversion: `→ ${destinationToken.symbol}`,
+        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 = {
+        id: `${candidate.id}-signature-2`,
+        label: `Bridge to ${(0, chain_names_js_1.chainDisplayName)(producers_js_1.pulsechainChainId)}`,
+        providerKey: omnibridgeProviderKey,
+        tokenFlow: [anchorNode, destinationNode],
+        landing: {
+            amount: candidate.deliveredAmount,
+            decimals: destinationToken.decimals,
+            symbol: destinationToken.symbol,
+            usdValue: (0, producers_js_1.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 ${(0, chain_names_js_1.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: producers_js_1.BRIDGE_SETTLEMENT_ETA_MINUTES,
+        hops: [crossingHop],
+    };
+    const totalCostUsdValue = aggregatorFeeUsd === null && crossingFeeUsd === null
+        ? null
+        : (aggregatorFeeUsd ?? 0) + (crossingFeeUsd ?? 0);
+    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: (0, producers_js_1.subtractUsdValues)(paidUsd, totalCostUsdValue),
+        },
+        totalCostUsdValue,
+        // Ranked on the same net figure as every other route: delivered value less
+        // everything the journey costs.
+        netValueUsd: (0, producers_js_1.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) + producers_js_1.BRIDGE_SETTLEMENT_ETA_MINUTES,
+    };
+};
+exports.buildNearIntentsTwoStepRouteData = buildNearIntentsTwoStepRouteData;
+/**
+ * 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
+ */
+const describeDeferredCrossing = ({ anchorToken, anchorAmount, anchorUsdValue, }) => {
+    if (anchorToken === null) {
+        return null;
+    }
+    if (anchorAmount === null || anchorAmount === undefined || anchorAmount <= 0n) {
+        return null;
+    }
+    return { anchorToken, anchorAmount, anchorUsdValue: anchorUsdValue ?? null };
+};
+exports.describeDeferredCrossing = describeDeferredCrossing;