@gibs/bridge-sdk 1.13.0 → 1.17.0

package/dist/cjs/pre-quote.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseLifiPreQuote = exports.parseRelayPreQuote = exports.buildLifiPreQuoteRequest = exports.buildRelayPreQuoteRequest = exports.lifiRequestHeaders = exports.lifiQuoteUrl = void 0;
+const url_1 = require("@gibs/common/url");
+const consolidated_quote_js_1 = require("./consolidated-quote.js");
+const referral_js_1 = require("./referral.js");
+const relay_quote_js_1 = require("./relay-quote.js");
+/**
+ * Plain LI.FI swap quote endpoint (forward-solving), re-exported from
+ * `consolidated-quote.js` rather than redeclared here — both modules must
+ * agree on the same address, and a second literal would be free to drift from
+ * it.
+ */
+var consolidated_quote_js_2 = require("./consolidated-quote.js");
+Object.defineProperty(exports, "lifiQuoteUrl", { enumerable: true, get: function () { return consolidated_quote_js_2.lifiQuoteUrl; } });
+Object.defineProperty(exports, "lifiRequestHeaders", { enumerable: true, get: function () { return consolidated_quote_js_2.lifiRequestHeaders; } });
+/**
+ * Builds the Relay EXACT_INPUT swap pre-quote body for a fixed input. NO `txs`
+ * are attached: Relay solves FORWARD and reports the delivered anchor amount.
+ *
+ * `recipient` and `refundTo` name TWO DIFFERENT chains and must never be
+ * conflated. `refundTo` is always the user's OWN origin-chain address — Relay
+ * refunds a failed (or, here, never-run) swap on the origin chain, and an
+ * Ethereum fallback address could not receive one there. `recipient` names
+ * where the swap lands on the ENTRY chain (`toChainId`), which is always
+ * Ethereum Virtual Machine — for an Ethereum origin the user's own address
+ * already satisfies that and is the default; for a non-Ethereum origin
+ * (Solana base58, Bitcoin bech32, ...) it does NOT, and Relay's `/quote/v2`
+ * validates the recipient's FORMAT against `toChainId` even though this
+ * pre-quote never executes. Sending the origin account there — as an earlier
+ * version of this builder did, reasoning that an unexecuted quote's recipient
+ * is "informational" — gets Relay's `400 INVALID_ADDRESS` on every
+ * non-Ethereum-origin pre-quote, which starves `fetchBestEntryAnchorPreQuote`
+ * of its only capable provider and surfaces as "No route available" for the
+ * whole non-Ethereum-origin flow. `request.recipient` (an explicit
+ * Ethereum-format address the caller supplies) is therefore REQUIRED for a
+ * non-Ethereum origin; without it this returns null.
+ *
+ * @param request - the provider-agnostic pre-quote request
+ * @returns the request body, or null when the input amount is non-positive or
+ *   a non-Ethereum origin has no explicit Ethereum-format `recipient`
+ */
+const buildRelayPreQuoteRequest = (request) => {
+    if (request.amount <= 0n) {
+        return null;
+    }
+    const nonEthereumOrigin = (0, consolidated_quote_js_1.isNonEthereumVirtualMachineOrigin)(request);
+    // A non-Ethereum origin's own address cannot stand in for an entry-chain
+    // recipient; it must be supplied explicitly. An Ethereum origin's own
+    // address already IS a valid entry-chain address, so it remains the default.
+    const recipient = nonEthereumOrigin ? request.recipient : (request.recipient ?? request.fromAddress);
+    if (recipient === undefined) {
+        return null;
+    }
+    return {
+        user: request.fromAddress,
+        originChainId: request.fromChainId,
+        originCurrency: request.fromTokenAddress,
+        destinationChainId: request.toChainId,
+        destinationCurrency: request.toTokenAddress,
+        amount: request.amount.toString(),
+        tradeType: 'EXACT_INPUT',
+        recipient,
+        // Relay always refunds on the ORIGIN chain, so the origin's own address
+        // is the correct refund target regardless of ecosystem — unlike
+        // `recipient` above, this one is deliberately NOT Ethereum-format for a
+        // non-Ethereum origin.
+        refundTo: request.fromAddress,
+        ...(0, relay_quote_js_1.relayReferrerField)(request),
+        ...(request.slippage === undefined
+            ? {}
+            : { slippageTolerance: (0, relay_quote_js_1.slippageToBasisPoints)(request.slippage) }),
+    };
+};
+exports.buildRelayPreQuoteRequest = buildRelayPreQuoteRequest;
+/**
+ * Builds the plain LI.FI swap pre-quote as a query string for `GET /v1/quote`.
+ * LI.FI's plain `/quote` is forward-solving by construction (`fromAmount` in,
+ * `estimate.toAmount` out), so no trade-type flag is needed.
+ *
+ * Returns null for a non-Ethereum origin (LI.FI cannot bridge across
+ * virtual-machine ecosystems) and for a non-positive input amount.
+ *
+ * @param request - the provider-agnostic pre-quote request
+ * @returns the URL query string (without a leading `?`), or null
+ */
+const buildLifiPreQuoteRequest = (request) => {
+    if (request.amount <= 0n) {
+        return null;
+    }
+    if ((0, consolidated_quote_js_1.isNonEthereumVirtualMachineOrigin)(request)) {
+        return null;
+    }
+    // Left out or `null` OMITS the query parameter (LI.FI's own schema marks it
+    // optional); a string is sent as-is. No package default: attribution is the
+    // caller's to choose. See `PreQuoteRequest.lifiIntegrator`'s doc.
+    const integrator = (0, referral_js_1.resolveAttribution)(request.lifiIntegrator, undefined);
+    return (0, url_1.buildQuery)({
+        fromChain: request.fromChainId.toString(),
+        toChain: request.toChainId.toString(),
+        fromToken: request.fromTokenAddress,
+        toToken: request.toTokenAddress,
+        fromAmount: request.amount.toString(),
+        fromAddress: request.fromAddress,
+        // Each optional parameter is left out when it is undefined.
+        integrator,
+        slippage: request.slippage?.toString(),
+    });
+};
+exports.buildLifiPreQuoteRequest = buildLifiPreQuoteRequest;
+const asRecord = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return null;
+    }
+    return value;
+};
+/**
+ * Parses a decimal-string amount into a bigint.
+ *
+ * @returns the bigint value, or null when the input is not a parseable amount
+ */
+const parseAmount = (value) => {
+    if (typeof value !== 'string' || value === '') {
+        return null;
+    }
+    try {
+        return BigInt(value);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Assembles the expected/minimum pair, defaulting the minimum to the expected
+ * amount when the provider omits a guaranteed floor. Shared by both parsers so
+ * the fallback rule lives in exactly one place.
+ *
+ * @returns the result, or null when the expected amount is absent
+ */
+const toPreQuoteResult = (expected, minimum) => {
+    const expectedAmount = parseAmount(expected);
+    if (expectedAmount === null) {
+        return null;
+    }
+    const minimumAmount = parseAmount(minimum);
+    return {
+        expectedAmount,
+        minimumAmount: minimumAmount ?? expectedAmount,
+    };
+};
+/**
+ * Parses a Relay EXACT_INPUT pre-quote response. The delivered anchor figures
+ * live under `details.currencyOut`: `amount` (expected) and `minimumAmount`
+ * (guaranteed slippage floor). Verified live against `api.relay.link/quote/v2`.
+ *
+ * @returns the delivered amounts, or null when the payload shape is unexpected
+ */
+const parseRelayPreQuote = (payload) => {
+    const currencyOut = asRecord(asRecord(asRecord(payload)?.details)?.currencyOut);
+    if (!currencyOut) {
+        return null;
+    }
+    return toPreQuoteResult(currencyOut.amount, currencyOut.minimumAmount);
+};
+exports.parseRelayPreQuote = parseRelayPreQuote;
+/**
+ * Parses a plain LI.FI `/quote` response. The delivered anchor figures live
+ * under `estimate`: `toAmount` (expected) and `toAmountMin` (guaranteed minimum
+ * after slippage) — the same estimate shape the route-step normalizer reads.
+ *
+ * @returns the delivered amounts, or null when the payload shape is unexpected
+ */
+const parseLifiPreQuote = (payload) => {
+    const estimate = asRecord(asRecord(payload)?.estimate);
+    if (!estimate) {
+        return null;
+    }
+    return toPreQuoteResult(estimate.toAmount, estimate.toAmountMin);
+};
+exports.parseLifiPreQuote = parseLifiPreQuote;

package/dist/cjs/prices.d.ts

@@ -0,0 +1,107 @@
+import { type Hex } from 'viem';
+import type { Token } from './types.js';
+/**
+ * PulseChain mainnet numeric chain id (`Chains.PLS` = `0x171`). Tokens on this
+ * chain (and its testnet sibling below) are priced on-chain via PulseX rather
+ * than from an off-chain price feed.
+ */
+export declare const PULSECHAIN_CHAIN_ID: number;
+/**
+ * PulseChain V4 testnet numeric chain id (`Chains.V4PLS` = `0x3af`). Shares the
+ * PulseX on-chain pricing path with mainnet.
+ */
+export declare const PULSECHAIN_TESTNET_CHAIN_ID: number;
+/**
+ * Bridged DAI on PulseChain (18 decimals) — the USD anchor stablecoin for
+ * on-chain PulseX pricing. One token's `getAmountsOut` ending in this address
+ * yields that token's USD price directly (DAI is treated as exactly $1).
+ *
+ * Kept as an exported constant so the anchor can be swapped without touching the
+ * pricing math. Mirrors `DAI_ADDRESS` in `packages/tx-report/src/server/prices.ts`.
+ */
+export declare const PULSECHAIN_USD_ANCHOR_ADDRESS: Hex;
+/** Decimals of the {@link PULSECHAIN_USD_ANCHOR_ADDRESS} stablecoin. */
+export declare const PULSECHAIN_USD_ANCHOR_DECIMALS = 18;
+/** Wrapped PLS on PulseChain — the routing intermediary for PulseX paths. */
+export declare const WPLS_ADDRESS: `0x${string}`;
+/** Lowercases an address for case-insensitive map keys and comparisons. */
+export declare const lowercaseAddress: (address: string) => string;
+/**
+ * Map key for a foreign (LI.FI-priced) token: `${chainId}-${lowercased address}`.
+ * Matches the key the UI builds when assembling the LI.FI price map.
+ */
+export declare const lifiPriceKey: (chainId: number, address: string) => string;
+/** True when a chain id is priced on-chain via PulseX (mainnet or V4 testnet). */
+export declare const isPulsechain: (chainId: number) => boolean;
+/**
+ * The PulseChain-origin address a bridged token backs out to, when the token's
+ * `extensions.bridgeInfo` records a PulseChain counterpart. Bridged tokens are
+ * 1:1 with their origin, so the origin's PulseX price is the token's USD value.
+ *
+ * @param token - the token whose PulseChain-origin link to resolve
+ * @returns the PulseChain origin address, or null when the token has no such link
+ */
+export declare const pulsechainOriginAddress: (token: Token) => Hex | null;
+/**
+ * The set of PulseX swap paths to price one whole unit of `token` into the USD
+ * anchor stablecoin. Edge cases collapse to shorter paths:
+ *
+ * - `token` is the stablecoin itself -> no swap needed (priced as exactly 1).
+ * - `token` is WPLS (or the native zero-address) -> `[WPLS, stable]` only.
+ * - otherwise -> both `[token, WPLS, stable]` and `[token, stable]`.
+ *
+ * Returned addresses are always concrete (the native sentinel is rewritten to
+ * WPLS) so they can be fed straight into `getAmountsOut`.
+ *
+ * @param options.token - the token (only its address is read) to build paths for
+ * @param options.wpls - the wrapped-native intermediary (defaults to {@link WPLS_ADDRESS})
+ * @param options.stable - the USD anchor (defaults to {@link PULSECHAIN_USD_ANCHOR_ADDRESS})
+ * @returns `{ paths }` — the candidate paths; empty when the token is the stablecoin
+ */
+export declare const pulsexPricePaths: ({ token, wpls, stable, }: {
+    token: Pick<Token, "address">;
+    wpls?: Hex;
+    stable?: Hex;
+}) => {
+    paths: Hex[][];
+};
+/**
+ * A single `getAmountsOut` outcome: the decoded `bigint[]` on success, or raw
+ * `Hex` return data when the (allowFailure) call reverted. Mirrors the
+ * `multicallRead` return shape so results can be passed in untransformed.
+ */
+export type AmountsOutResult = bigint[] | Hex;
+/**
+ * Reduces every `getAmountsOut` result (across all paths and all routers for one
+ * token) to a single USD price by taking the MAX final output, then scaling out
+ * of the stablecoin's decimals. Failed/empty results are dropped; when none
+ * succeed the price is null (no liquidity).
+ *
+ * @param options.results - the `getAmountsOut` outcomes for the token's paths/routers
+ * @param options.stableDecimals - decimals of the anchor (defaults to {@link PULSECHAIN_USD_ANCHOR_DECIMALS})
+ * @returns the USD price as a number, or null when no path produced a value
+ */
+export declare const computeUsdPriceFromAmountsOut: ({ results, stableDecimals, }: {
+    results: readonly AmountsOutResult[];
+    stableDecimals?: number;
+}) => number | null;
+/**
+ * Resolves a token's USD price using pre-fetched price maps, following the
+ * co-designed precedence:
+ *
+ * 1. PulseChain (mainnet or V4 testnet): the token's own PulseX price.
+ * 2. Bridged PulseChain-origin token: the origin's PulseX price (1:1 value).
+ * 3. Genuinely foreign token: the LI.FI inline price.
+ *
+ * The stablecoin anchor itself resolves to exactly 1. All address lookups are
+ * case-insensitive (maps are keyed by lowercased address).
+ *
+ * @param token - the token to price
+ * @param options.pulsexPrices - lowercased PulseChain address -> USD price
+ * @param options.lifiPrices - `${chainId}-${lowercased address}` -> USD price
+ * @returns the USD price as a number, or null when no source can price it
+ */
+export declare const resolveTokenPriceUsd: (token: Token, { pulsexPrices, lifiPrices, }: {
+    pulsexPrices: Map<string, number>;
+    lifiPrices: Map<string, number>;
+}) => number | null;

package/dist/cjs/prices.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTokenPriceUsd = exports.computeUsdPriceFromAmountsOut = exports.pulsexPricePaths = exports.pulsechainOriginAddress = exports.isPulsechain = exports.lifiPriceKey = exports.lowercaseAddress = exports.WPLS_ADDRESS = exports.PULSECHAIN_USD_ANCHOR_DECIMALS = exports.PULSECHAIN_USD_ANCHOR_ADDRESS = exports.PULSECHAIN_TESTNET_CHAIN_ID = exports.PULSECHAIN_CHAIN_ID = void 0;
+const viem_1 = require("viem");
+const config_js_1 = require("./config.js");
+/**
+ * PulseChain mainnet numeric chain id (`Chains.PLS` = `0x171`). Tokens on this
+ * chain (and its testnet sibling below) are priced on-chain via PulseX rather
+ * than from an off-chain price feed.
+ */
+exports.PULSECHAIN_CHAIN_ID = Number(config_js_1.Chains.PLS);
+/**
+ * PulseChain V4 testnet numeric chain id (`Chains.V4PLS` = `0x3af`). Shares the
+ * PulseX on-chain pricing path with mainnet.
+ */
+exports.PULSECHAIN_TESTNET_CHAIN_ID = Number(config_js_1.Chains.V4PLS);
+/**
+ * Bridged DAI on PulseChain (18 decimals) — the USD anchor stablecoin for
+ * on-chain PulseX pricing. One token's `getAmountsOut` ending in this address
+ * yields that token's USD price directly (DAI is treated as exactly $1).
+ *
+ * Kept as an exported constant so the anchor can be swapped without touching the
+ * pricing math. Mirrors `DAI_ADDRESS` in `packages/tx-report/src/server/prices.ts`.
+ */
+exports.PULSECHAIN_USD_ANCHOR_ADDRESS = '0xefd766ccb38eaf1dfd701853bfce31359239f305';
+/** Decimals of the {@link PULSECHAIN_USD_ANCHOR_ADDRESS} stablecoin. */
+exports.PULSECHAIN_USD_ANCHOR_DECIMALS = 18;
+/** Wrapped PLS on PulseChain — the routing intermediary for PulseX paths. */
+exports.WPLS_ADDRESS = config_js_1.nativeAssetOut[config_js_1.Chains.PLS];
+/** The native (gas) token sentinel address used across the dapp. */
+const NATIVE_TOKEN_ADDRESS = '0x0000000000000000000000000000000000000000';
+/** Lowercases an address for case-insensitive map keys and comparisons. */
+const lowercaseAddress = (address) => address.toLowerCase();
+exports.lowercaseAddress = lowercaseAddress;
+/** True when two addresses are equal ignoring case (and 0x-checksum casing). */
+const sameAddress = (left, right) => (0, exports.lowercaseAddress)(left) === (0, exports.lowercaseAddress)(right);
+/**
+ * Map key for a foreign (LI.FI-priced) token: `${chainId}-${lowercased address}`.
+ * Matches the key the UI builds when assembling the LI.FI price map.
+ */
+const lifiPriceKey = (chainId, address) => `${chainId}-${(0, exports.lowercaseAddress)(address)}`;
+exports.lifiPriceKey = lifiPriceKey;
+/** True when a chain id is priced on-chain via PulseX (mainnet or V4 testnet). */
+const isPulsechain = (chainId) => chainId === exports.PULSECHAIN_CHAIN_ID || chainId === exports.PULSECHAIN_TESTNET_CHAIN_ID;
+exports.isPulsechain = isPulsechain;
+/**
+ * The PulseChain-origin address a bridged token backs out to, when the token's
+ * `extensions.bridgeInfo` records a PulseChain counterpart. Bridged tokens are
+ * 1:1 with their origin, so the origin's PulseX price is the token's USD value.
+ *
+ * @param token - the token whose PulseChain-origin link to resolve
+ * @returns the PulseChain origin address, or null when the token has no such link
+ */
+const pulsechainOriginAddress = (token) => {
+    const link = token.extensions?.bridgeInfo?.[exports.PULSECHAIN_CHAIN_ID];
+    if (!link) {
+        return null;
+    }
+    return link.tokenAddress;
+};
+exports.pulsechainOriginAddress = pulsechainOriginAddress;
+/**
+ * The set of PulseX swap paths to price one whole unit of `token` into the USD
+ * anchor stablecoin. Edge cases collapse to shorter paths:
+ *
+ * - `token` is the stablecoin itself -> no swap needed (priced as exactly 1).
+ * - `token` is WPLS (or the native zero-address) -> `[WPLS, stable]` only.
+ * - otherwise -> both `[token, WPLS, stable]` and `[token, stable]`.
+ *
+ * Returned addresses are always concrete (the native sentinel is rewritten to
+ * WPLS) so they can be fed straight into `getAmountsOut`.
+ *
+ * @param options.token - the token (only its address is read) to build paths for
+ * @param options.wpls - the wrapped-native intermediary (defaults to {@link WPLS_ADDRESS})
+ * @param options.stable - the USD anchor (defaults to {@link PULSECHAIN_USD_ANCHOR_ADDRESS})
+ * @returns `{ paths }` — the candidate paths; empty when the token is the stablecoin
+ */
+const pulsexPricePaths = ({ token, wpls = exports.WPLS_ADDRESS, stable = exports.PULSECHAIN_USD_ANCHOR_ADDRESS, }) => {
+    const address = sameAddress(token.address, NATIVE_TOKEN_ADDRESS) ? wpls : token.address;
+    if (sameAddress(address, stable)) {
+        return { paths: [] };
+    }
+    if (sameAddress(address, wpls)) {
+        return { paths: [[wpls, stable]] };
+    }
+    return {
+        paths: [
+            [address, wpls, stable],
+            [address, stable],
+        ],
+    };
+};
+exports.pulsexPricePaths = pulsexPricePaths;
+/**
+ * The final output amount of one `getAmountsOut` result, or null when the call
+ * failed (Hex) or returned an empty array. The last element of a `bigint[]`
+ * `getAmountsOut` is the output-token amount.
+ */
+const finalOutput = (result) => {
+    if (typeof result === 'string') {
+        return null;
+    }
+    if (result.length === 0) {
+        return null;
+    }
+    return result[result.length - 1];
+};
+/**
+ * Reduces every `getAmountsOut` result (across all paths and all routers for one
+ * token) to a single USD price by taking the MAX final output, then scaling out
+ * of the stablecoin's decimals. Failed/empty results are dropped; when none
+ * succeed the price is null (no liquidity).
+ *
+ * @param options.results - the `getAmountsOut` outcomes for the token's paths/routers
+ * @param options.stableDecimals - decimals of the anchor (defaults to {@link PULSECHAIN_USD_ANCHOR_DECIMALS})
+ * @returns the USD price as a number, or null when no path produced a value
+ */
+const computeUsdPriceFromAmountsOut = ({ results, stableDecimals = exports.PULSECHAIN_USD_ANCHOR_DECIMALS, }) => {
+    const outputs = results.flatMap((result) => {
+        const output = finalOutput(result);
+        return output === null ? [] : [output];
+    });
+    if (outputs.length === 0) {
+        return null;
+    }
+    const maxOutput = outputs.reduce((max, current) => (current > max ? current : max), 0n);
+    if (maxOutput === 0n) {
+        return null;
+    }
+    return Number((0, viem_1.formatUnits)(maxOutput, stableDecimals));
+};
+exports.computeUsdPriceFromAmountsOut = computeUsdPriceFromAmountsOut;
+/**
+ * Resolves a token's USD price using pre-fetched price maps, following the
+ * co-designed precedence:
+ *
+ * 1. PulseChain (mainnet or V4 testnet): the token's own PulseX price.
+ * 2. Bridged PulseChain-origin token: the origin's PulseX price (1:1 value).
+ * 3. Genuinely foreign token: the LI.FI inline price.
+ *
+ * The stablecoin anchor itself resolves to exactly 1. All address lookups are
+ * case-insensitive (maps are keyed by lowercased address).
+ *
+ * @param token - the token to price
+ * @param options.pulsexPrices - lowercased PulseChain address -> USD price
+ * @param options.lifiPrices - `${chainId}-${lowercased address}` -> USD price
+ * @returns the USD price as a number, or null when no source can price it
+ */
+const resolveTokenPriceUsd = (token, { pulsexPrices, lifiPrices, }) => {
+    if ((0, exports.isPulsechain)(token.chainId)) {
+        if (sameAddress(token.address, exports.PULSECHAIN_USD_ANCHOR_ADDRESS)) {
+            return 1;
+        }
+        return pulsexPrices.get((0, exports.lowercaseAddress)(token.address)) ?? null;
+    }
+    const origin = (0, exports.pulsechainOriginAddress)(token);
+    if (origin) {
+        if (sameAddress(origin, exports.PULSECHAIN_USD_ANCHOR_ADDRESS)) {
+            return 1;
+        }
+        // Prefer the bridged origin's on-chain PulseX price. Fall back to the token's
+        // OWN home-chain LI.FI inline price when PulseX cannot price it — a bridged
+        // major (e.g. wrapped ether / wrapped binance coin) whose PulseChain pool path
+        // returns nothing would otherwise resolve to null despite a well-known market
+        // price on its home chain.
+        return (pulsexPrices.get((0, exports.lowercaseAddress)(origin)) ??
+            lifiPrices.get((0, exports.lifiPriceKey)(token.chainId, token.address)) ??
+            null);
+    }
+    return lifiPrices.get((0, exports.lifiPriceKey)(token.chainId, token.address)) ?? null;
+};
+exports.resolveTokenPriceUsd = resolveTokenPriceUsd;