@gibs/bridge-sdk 1.13.0 → 1.17.0

package/dist/cjs/settings.js

@@ -0,0 +1,1074 @@
+"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.assetOut = exports.assetOutKey = exports.transactionInputs = exports.pulseXSwapTransactionInputs = exports.assertCandidatePickAgrees = exports.candidatePickRefusal = exports.assertSwapAgrees = exports.swapRefusal = exports.assertCrossingAgrees = exports.crossingRefusal = exports.isUndercompensated = exports.availableCompensationMaximum = exports.desiredCompensationRatio = exports.reasonablePercentOnTopOfGasFee = exports.destinationDataParam = exports.feeDirectorStructEncoded = exports.interactingWithBridgeToken = exports.reasonablePercentFee = exports.reasonablePercentOnGasLimit = exports.reasonableFixedFee = exports.omnibridgeApproval = exports.approvalAmounts = exports.approveCall = exports.feeTypeSettings = exports.deliveryFee = exports.desiredExcessCompensationBasisPoints = exports.networkSwitchAssetOutAddress = exports.limit = exports.oneTokenInt = exports.estimatedTokenNetworkCost = exports.estimatedNativeNetworkCost = exports.estimatedFee = exports.estimatedAmountOut = exports.amountAfterBridgeFee = exports.bridgeCost = exports.amountToBridge = exports.bridgePathway = exports.basisPoints = exports.oneEther = void 0;
+const viem_1 = require("viem");
+const abis = __importStar(require("./abis.js"));
+const config_js_1 = require("./config.js");
+const fee_type_js_1 = require("./fee-type.js");
+exports.oneEther = 10n ** 18n;
+exports.basisPoints = 10000n;
+/**
+ * Returns the bridge pathway (configuration) for a given bridge key, asset in, and whether to use the production pathway
+ * @param bridgeKey - the bridge key to use
+ * @param isProd - whether to use the production pathway
+ * @param assetIn - the asset in to bridge
+ * @returns the bridge pathway
+ */
+const bridgePathway = ({ bridgeKey, isProd, assetIn, }) => (0, config_js_1.pathway)(bridgeKey, isProd, assetIn?.address) ?? null;
+exports.bridgePathway = bridgePathway;
+/**
+ * Retrieves the amount to bridge from the amount and asset in. If either of them is nil, returns 0n
+ * @param amountIn - the amount to bridge
+ * @param assetIn - the asset in to bridge
+ * @returns the amount to bridge
+ */
+const amountToBridge = ({ amountIn, assetIn, }) => {
+    if (!amountIn || amountIn === 0n || !assetIn) {
+        return 0n;
+    }
+    return amountIn;
+};
+exports.amountToBridge = amountToBridge;
+/**
+ * Calculates the bridge cost from the amount to bridge and bridge fee
+ * @param amountToBridge - the amount to bridge
+ * @param bridgeFee - the bridge fee
+ * @returns the bridge cost
+ */
+const bridgeCost = ({ amountToBridge, bridgeFee, }) => {
+    if (bridgeFee === null)
+        return null;
+    return (amountToBridge * bridgeFee) / exports.oneEther;
+};
+exports.bridgeCost = bridgeCost;
+/**
+ * Calculates the amount after bridge fee from the amount to bridge and bridge cost
+ * @param amountToBridge - the amount to bridge
+ * @param bridgeCost - the bridge cost
+ * @returns the amount after bridge fee
+ */
+const amountAfterBridgeFee = ({ amountToBridge, bridgeCost, }) => {
+    if (bridgeCost === null)
+        return null;
+    const afterFee = amountToBridge - bridgeCost;
+    if (afterFee < 0n)
+        return 0n;
+    return afterFee;
+};
+exports.amountAfterBridgeFee = amountAfterBridgeFee;
+/**
+ * Calculates the estimated amount out from the amount after bridge fee and fee
+ * @param amountAfterBridgeFee - the amount after bridge fee
+ * @param fee - the fee
+ * @returns the estimated amount out
+ */
+const estimatedAmountOut = ({ amountAfterBridgeFee, fee, }) => {
+    if (typeof fee !== 'bigint')
+        return null;
+    if (amountAfterBridgeFee === null)
+        return null;
+    if (fee > amountAfterBridgeFee)
+        return 0n;
+    return amountAfterBridgeFee - fee;
+};
+exports.estimatedAmountOut = estimatedAmountOut;
+/**
+ * Calculates the estimated fee from the amount after bridge fee, fee, percent fee, fee type, limit, and whether to deliver the costs
+ * @param amountAfterBridgeFee - the amount after bridge fee
+ * @param fee - the fee
+ * @param percentFee - the percent fee
+ * @param feeType - the fee type
+ * @param limit - the limit
+ * @param costsToDeliver - whether to deliver the costs
+ * @returns the estimated fee
+ */
+const estimatedFee = ({ amountAfterBridgeFee, fee, percentFee, feeType, limit, costsToDeliver, }) => {
+    const fixedFee = amountAfterBridgeFee ? (amountAfterBridgeFee * percentFee) / exports.oneEther : null;
+    if (!costsToDeliver) {
+        return 0n;
+    }
+    if (feeType === fee_type_js_1.FeeType.FIXED) {
+        return fee;
+    }
+    else if (feeType === fee_type_js_1.FeeType.PERCENT) {
+        if (amountAfterBridgeFee === null)
+            return null;
+        return fixedFee;
+    }
+    else if (feeType === fee_type_js_1.FeeType.GAS_TIP) {
+        return limit;
+    }
+    return null;
+};
+exports.estimatedFee = estimatedFee;
+/**
+ * Calculates the estimated native network cost from the estimated gas and latest base fee per gas
+ * @param estimatedGas - the estimated gas
+ * @param latestBaseFeePerGas - the latest base fee per gas
+ * @param requiresDelivery - whether to deliver the costs
+ * @returns the estimated native network cost
+ */
+const estimatedNativeNetworkCost = ({ estimatedGas, latestBaseFeePerGas, requiresDelivery, }) => {
+    if (!estimatedGas || !latestBaseFeePerGas || !requiresDelivery) {
+        return null;
+    }
+    return BigInt(estimatedGas * latestBaseFeePerGas);
+};
+exports.estimatedNativeNetworkCost = estimatedNativeNetworkCost;
+/**
+ * Calculates the estimated token network cost from the estimated native
+ * network cost, price corrective, decimals, and one token int
+ * @param estimatedNativeNetworkCost - the estimated native network cost
+ * @param priceCorrective - the price corrective
+ * @param decimals - the decimals
+ * @param oneTokenInt - the one token int
+ * @returns the estimated token network cost
+ */
+const estimatedTokenNetworkCost = ({ estimatedNativeNetworkCost, priceCorrective, decimals, oneTokenInt, }) => {
+    if (!priceCorrective || !oneTokenInt || !estimatedNativeNetworkCost || !decimals) {
+        return null;
+    }
+    const tokenCost = (estimatedNativeNetworkCost * oneTokenInt) / priceCorrective;
+    return tokenCost;
+};
+exports.estimatedTokenNetworkCost = estimatedTokenNetworkCost;
+/**
+ * Calculates one token of the asset in as an int
+ * @param assetIn - the asset in to bridge
+ * @returns the one token int
+ */
+const oneTokenInt = ({ assetIn }) => {
+    if (!assetIn)
+        return 1n;
+    return 10n ** BigInt(assetIn.decimals);
+};
+exports.oneTokenInt = oneTokenInt;
+/**
+ * Returns the limit as a bigint. Nil uses 0n
+ * @param lim - the limit
+ * @returns the limit
+ */
+const limit = (lim) => {
+    if (!lim) {
+        return 0n;
+    }
+    return lim;
+};
+exports.limit = limit;
+/**
+ * Returns the network switch asset out address from the asset out, unwrap, and to chain
+ * @param assetOut - the asset out
+ * @param unwrap - whether to unwrap
+ * @param toChain - the chain to switch to
+ * @returns the network switch asset out address
+ */
+const networkSwitchAssetOutAddress = ({ assetOut, unwrap, toChain, }) => {
+    if (!assetOut)
+        return null;
+    if (!unwrap)
+        return assetOut.address;
+    const wrappedNative = config_js_1.nativeAssetOut[toChain];
+    // Addresses arrive in whatever case their source used (a checksummed literal
+    // here, a lower-cased list entry there), so equality must ignore case.
+    const isWrappedNative = !!wrappedNative && (0, viem_1.isAddress)(assetOut.address, { strict: false }) && (0, viem_1.isAddressEqual)(wrappedNative, assetOut.address);
+    return isWrappedNative ? viem_1.zeroAddress : assetOut.address;
+};
+exports.networkSwitchAssetOutAddress = networkSwitchAssetOutAddress;
+/**
+ * Calculates the desired excess compensation basis points from the path, asset in, asset out, bridge key, fee type, list, and asset out address
+ * @param path - the path
+ * @param assetIn - the asset in to bridge
+ * @param assetOut - the asset out
+ * @param bridgeKey - the bridge key
+ * @param feeType - the fee type
+ * @param list - the list
+ * @param assetOutAddress - the asset out address
+ * @returns the desired excess compensation basis points
+ */
+const desiredExcessCompensationBasisPoints = ({ path, assetIn, assetOut, bridgeKey, feeType, list, assetOutAddress, }) => {
+    if (!path?.requiresDelivery) {
+        return 0n;
+    }
+    return !assetIn
+        ? 0n
+        : feeType === fee_type_js_1.FeeType.PERCENT
+            ? 1000n
+            : (0, config_js_1.isNative)(assetIn, bridgeKey) || (0, config_js_1.isNative)(assetOut, bridgeKey)
+                ? 1000n
+                : list.has((0, viem_1.getAddress)(assetIn?.address ?? '')) ||
+                    list.has(assetOutAddress ? (0, viem_1.getAddress)(assetOutAddress) : '0x')
+                    ? 5000n
+                    : 10000n;
+};
+exports.desiredExcessCompensationBasisPoints = desiredExcessCompensationBasisPoints;
+/**
+ * Works out the Gibs delivery fee for a transfer, as a {@link DeliveryFee}.
+ *
+ * Each mode reads the SAME figure the delivered estimate subtracts
+ * ({@link estimatedFee}), so a route's cost and its delivered value reconcile:
+ *
+ * - percent: the arriving value times the rate. The router computes
+ *   `value * multiplier / 1 ether`.
+ * - fixed: the fixed amount. The router takes `limit` as the fee.
+ * - gas: the limit. The router takes the gas cost, capped at the limit, so the
+ *   limit is the most the reader pays and the figure the delivered estimate
+ *   already assumes.
+ *
+ * `percentFee` must be null when the rate is not known. Passing a zero stand-in
+ * would state a free delivery.
+ *
+ * @param options.shouldDeliver - whether the reader asked for delivery
+ * @param options.routeOffersDelivery - whether this pathway delivers for a fee at all
+ * @param options.feeType - the delivery fee mode
+ * @param options.amountAfterBridgeFee - the value that reaches the destination router, or null
+ * @param options.percentFee - the percent rate as a fraction of one ether, or null when unknown
+ * @param options.fixedFee - the fixed fee in base units, or null when unknown
+ * @param options.limit - the gas mode cap in base units, or null when unknown
+ * @returns the delivery fee
+ */
+const deliveryFee = ({ shouldDeliver, routeOffersDelivery, feeType, amountAfterBridgeFee, percentFee, fixedFee, limit, }) => {
+    if (!shouldDeliver || !routeOffersDelivery) {
+        return { status: 'not-requested' };
+    }
+    if (feeType === fee_type_js_1.FeeType.FIXED) {
+        return { status: 'requested', amount: fixedFee, rate: null };
+    }
+    if (feeType === fee_type_js_1.FeeType.GAS_TIP) {
+        return { status: 'requested', amount: limit, rate: null };
+    }
+    if (amountAfterBridgeFee === null || percentFee === null) {
+        return { status: 'requested', amount: null, rate: percentFee };
+    }
+    return {
+        status: 'requested',
+        amount: (amountAfterBridgeFee * percentFee) / exports.oneEther,
+        rate: percentFee,
+    };
+};
+exports.deliveryFee = deliveryFee;
+/**
+ * The four-bit fee-type settings word a fee director carries.
+ *
+ * - bit 0: fixed fee mode.
+ * - bit 1: unwrap the delivered token to the native coin.
+ * - bit 2: exclude the priority fee from the delivery cost. Always set.
+ * - bit 3: percent fee mode.
+ *
+ * @param options.feeType - the delivery fee mode
+ * @param options.unwrap - whether the delivery unwraps to the native coin
+ * @returns the settings word for {@link feeDirectorStructEncoded}
+ */
+const feeTypeSettings = ({ feeType, unwrap }) => {
+    const fixedBit = feeType === fee_type_js_1.FeeType.FIXED ? 1n : 0n;
+    const unwrapBit = unwrap ? 1n : 0n;
+    const excludePriorityBit = 1n;
+    const percentBit = feeType === fee_type_js_1.FeeType.PERCENT ? 1n : 0n;
+    return (percentBit << 3n) | (excludePriorityBit << 2n) | (unwrapBit << 1n) | fixedBit;
+};
+exports.feeTypeSettings = feeTypeSettings;
+/**
+ * The ERC-20 `approve` call, as a target, a value and calldata. The
+ * interface's approval broadcast and the SDK's execution planner both build it
+ * here.
+ *
+ * @param options.token - the token to approve
+ * @param options.spender - the address allowed to pull it
+ * @param options.amount - the allowance to set
+ * @returns the call
+ */
+const approveCall = ({ token, spender, amount, }) => ({
+    to: token,
+    value: 0n,
+    data: (0, viem_1.encodeFunctionData)({ abi: viem_1.erc20Abi, functionName: 'approve', args: [spender, amount] }),
+});
+exports.approveCall = approveCall;
+/**
+ * The `approve` amounts to send, in order, so the spender may pull exactly
+ * `minimum`. Empty when the allowance on chain already covers it.
+ *
+ * EXACT, NEVER UNLIMITED. An unlimited approval lets the spender pull the
+ * reader's whole balance for as long as the approval stands, so a later fault
+ * in that contract, or a spender a compromised quote named, costs everything
+ * rather than one transfer. The owner chose exact approvals everywhere
+ * (2026-10-07); the interface and the SDK's execution planner both decide
+ * here.
+ *
+ * A SHORT, NON-ZERO ALLOWANCE IS RESET TO ZERO FIRST. Some tokens (Tether on
+ * Ethereum is the known one) revert an `approve` that changes one non-zero
+ * allowance into another. Exact approvals leave such remainders more often,
+ * because an aggregator may spend less than it was allowed. A reset first
+ * works for every token, at the cost of one extra transaction in that case.
+ *
+ * @param options.allowance - the allowance on chain now
+ * @param options.minimum - the amount the next transaction pulls
+ * @returns the amounts to approve, in order: none, `[minimum]`, or `[0n, minimum]`
+ */
+const approvalAmounts = ({ allowance, minimum, }) => {
+    if (allowance >= minimum)
+        return [];
+    if (allowance === 0n)
+        return [minimum];
+    return [0n, minimum];
+};
+exports.approvalAmounts = approvalAmounts;
+/**
+ * The allowance a direct omnibridge crossing needs, or null when it needs none.
+ *
+ * Reads the SAME predicate {@link transactionInputs} uses to pick the call: a
+ * token the bridge minted ({@link interactingWithBridgeToken}) is burned by
+ * `transferAndCall` and needs no allowance, and the native coin is sent as
+ * value. Every other token is pulled by the pathway's `from` mediator through
+ * `relayTokens` or `relayTokensAndCall`.
+ *
+ * @param options.bridgePathway - the crossing's pathway
+ * @param options.assetIn - the token the crossing spends
+ * @param options.assetLink - the token's bridge link
+ * @param options.amountToBridge - the amount the crossing pulls
+ * @returns the approval the crossing needs, or null
+ */
+const omnibridgeApproval = ({ bridgePathway, assetIn, assetLink, amountToBridge, }) => {
+    if (assetIn.address === viem_1.zeroAddress)
+        return null;
+    if ((0, exports.interactingWithBridgeToken)({ assetLink, assetInAddress: assetIn.address }))
+        return null;
+    return {
+        chainId: assetIn.chainId,
+        token: assetIn.address,
+        spender: bridgePathway.from,
+        minimum: amountToBridge,
+    };
+};
+exports.omnibridgeApproval = omnibridgeApproval;
+/**
+ * Calculates the reasonable fixed fee from the estimated token network cost and desired excess compensation basis points
+ * @param estimatedTokenNetworkCost - the estimated token network cost
+ * @param desiredExcessCompensationBasisPoints - the desired excess compensation basis points
+ * @returns the reasonable fixed fee
+ */
+const reasonableFixedFee = ({ estimatedTokenNetworkCost, desiredExcessCompensationBasisPoints, }) => {
+    if (!estimatedTokenNetworkCost) {
+        return null;
+    }
+    return ((estimatedTokenNetworkCost * (25000n + desiredExcessCompensationBasisPoints)) / exports.basisPoints);
+};
+exports.reasonableFixedFee = reasonableFixedFee;
+/**
+ * Calculates the reasonable percent on gas limit from the gas tip fee and estimated token network cost
+ * @param gasTipFee - the gas tip fee
+ * @param estimatedTokenNetworkCost - the estimated token network cost
+ * @returns the reasonable percent on gas limit
+ */
+const reasonablePercentOnGasLimit = ({ gasTipFee, estimatedTokenNetworkCost, }) => {
+    return ((25000n * ((exports.oneEther + (gasTipFee ?? 0n)) * (estimatedTokenNetworkCost ?? 0n))) /
+        (exports.oneEther * exports.basisPoints));
+};
+exports.reasonablePercentOnGasLimit = reasonablePercentOnGasLimit;
+/**
+ * Calculates the reasonable percent fee from the reasonable fixed fee and amount after bridge fee
+ * @param reasonableFixedFee - the reasonable fixed fee
+ * @param amountAfterBridgeFee - the amount after bridge fee
+ * @returns the reasonable percent fee
+ */
+const reasonablePercentFee = ({ reasonableFixedFee, amountAfterBridgeFee, }) => {
+    if (!reasonableFixedFee) {
+        return null;
+    }
+    if (!amountAfterBridgeFee) {
+        return null;
+    }
+    const highFee = amountAfterBridgeFee / 10n;
+    const basisFeeTruncator = 10n ** 14n;
+    const max = 1000n * basisFeeTruncator;
+    const min = 5n * basisFeeTruncator;
+    if (highFee < reasonableFixedFee) {
+        return max; // 10%
+    }
+    const highResPercent = (reasonableFixedFee * exports.oneEther) / amountAfterBridgeFee;
+    if (highResPercent < min) {
+        return min;
+    }
+    else if (highResPercent > max) {
+        return max;
+    }
+    const basisPoint = highResPercent / basisFeeTruncator;
+    return basisPoint * basisFeeTruncator;
+};
+exports.reasonablePercentFee = reasonablePercentFee;
+/**
+ * Returns whether the asset in address is interacting with a bridge token
+ * @param assetLink - the asset link
+ * @param assetInAddress - the asset in address
+ * @returns whether the asset in address is interacting with a bridge token
+ */
+const interactingWithBridgeToken = ({ assetLink, assetInAddress, }) => {
+    const { toForeign, toHome } = assetLink || {};
+    const { foreign } = toForeign || {};
+    const { home } = toHome || {};
+    if (!assetInAddress)
+        return false;
+    return !!((foreign && (0, viem_1.getAddress)(foreign) === (0, viem_1.getAddress)(assetInAddress)) ||
+        (home && (0, viem_1.getAddress)(home) === (0, viem_1.getAddress)(assetInAddress)));
+};
+exports.interactingWithBridgeToken = interactingWithBridgeToken;
+/**
+ * Calculates the fee director struct encoded from the recipient, bridge pathway, fee type, price corrective, gas tip fee, percent fee, fee type settings, limit, and asset out
+ * @param recipient - the recipient
+ * @param bridgePathway - the bridge pathway
+ * @param feeType - the fee type
+ * @param priceCorrective - the price corrective
+ * @param gasTipFee - the gas tip fee
+ * @param percentFee - the percent fee
+ * @param feeTypeSettings - the fee type settings
+ * @param limit - the limit
+ * @param assetOut - the asset out
+ * @returns the fee director struct encoded
+ */
+const feeDirectorStructEncoded = ({ recipient, bridgePathway, feeType, priceCorrective, gasTipFee, percentFee, feeTypeSettings, limit, assetOut, }) => {
+    if (!assetOut || !bridgePathway) {
+        return null;
+    }
+    if (!bridgePathway.requiresDelivery) {
+        return null;
+    }
+    if (!priceCorrective) {
+        return null;
+    }
+    let multiplier = 0n;
+    if (feeType === fee_type_js_1.FeeType.GAS_TIP && priceCorrective > 0n) {
+        multiplier =
+            ((exports.oneEther + (gasTipFee ?? 0n)) * 10n ** BigInt(assetOut.decimals)) / priceCorrective;
+    }
+    else if (feeType === fee_type_js_1.FeeType.PERCENT) {
+        multiplier = percentFee ?? 0n;
+    }
+    if (!recipient || !(0, viem_1.isAddress)(recipient)) {
+        return null;
+    }
+    return (0, viem_1.encodeAbiParameters)(abis.feeDeliveryStruct, [
+        [recipient, feeTypeSettings, limit, multiplier],
+    ]);
+};
+exports.feeDirectorStructEncoded = feeDirectorStructEncoded;
+/**
+ * Calculates the destination data param from the recipient, bridge pathway, asset in, destination router, fee director struct encoded, asset link, should deliver, and unwrap
+ * @param recipient - the recipient
+ * @param bridgePathway - the bridge pathway
+ * @param assetIn - the asset in to bridge
+ * @param destinationRouter - the destination router
+ * @param feeDirectorStructEncoded - the fee director struct encoded
+ * @param assetLink - the asset link
+ * @param shouldDeliver - whether to deliver the costs
+ * @param unwrap - whether to unwrap
+ * @returns the destination data param
+ */
+const destinationDataParam = ({ recipient, bridgePathway, assetIn, destinationRouter, feeDirectorStructEncoded, assetLink, shouldDeliver, unwrap, }) => {
+    // const recipient = input.recipient.value
+    if (!recipient) {
+        return null;
+    }
+    if (!bridgePathway || !assetIn) {
+        return null;
+    }
+    if (!destinationRouter) {
+        return null;
+    }
+    // Only a delivery needs the fee director. A crossing without delivery sends
+    // to the recipient, whatever the fee director would have said.
+    if (bridgePathway.requiresDelivery && shouldDeliver && !feeDirectorStructEncoded) {
+        return null;
+    }
+    if (!assetLink) {
+        return null;
+    }
+    if (bridgePathway.requiresDelivery) {
+        // going from home to foreign
+        if (!shouldDeliver) {
+            // act like a regular bridge
+            return recipient;
+        }
+        // going from foreign to home
+        if (feeDirectorStructEncoded) {
+            return (0, viem_1.concatHex)([destinationRouter, feeDirectorStructEncoded]);
+        }
+        return recipient;
+    }
+    if (!unwrap) {
+        return recipient;
+    }
+    // unwrap wpls->pls
+    return (0, viem_1.concatHex)([destinationRouter, recipient]);
+};
+exports.destinationDataParam = destinationDataParam;
+/**
+ * Converts a desired excess compensation basis point value into a percentage as an integer, with the denominator assumed to be 1e18
+ * @param desiredExcessCompensationBasisPoints - the desired excess compensation basis points
+ * @returns the reasonable percent on top of gas fee
+ */
+const reasonablePercentOnTopOfGasFee = ({ desiredExcessCompensationBasisPoints, }) => {
+    return desiredExcessCompensationBasisPoints * (exports.oneEther / exports.basisPoints);
+};
+exports.reasonablePercentOnTopOfGasFee = reasonablePercentOnTopOfGasFee;
+/**
+ * Calculates the desired compensation ratio from the desired excess compensation basis points
+ * @param desiredExcessCompensationBasisPoints - the desired excess compensation basis points
+ * @returns the desired compensation ratio
+ */
+const desiredCompensationRatio = ({ desiredExcessCompensationBasisPoints, }) => {
+    return exports.oneEther + (desiredExcessCompensationBasisPoints * exports.oneEther) / exports.basisPoints;
+};
+exports.desiredCompensationRatio = desiredCompensationRatio;
+/**
+ * Calculates the available compensation maximum from the amount after bridge fee, percent fee, fee type, fixed fee, and limit
+ * @param amountAfterBridgeFee - the amount after bridge fee
+ * @param percentFee - the percent fee
+ * @param feeType - the fee type
+ * @param fixedFee - the fixed fee
+ * @param limit - the limit
+ * @returns the available compensation maximum
+ */
+const availableCompensationMaximum = ({ amountAfterBridgeFee, percentFee, feeType, fixedFee, limit, }) => {
+    if (feeType === fee_type_js_1.FeeType.PERCENT) {
+        if (amountAfterBridgeFee === null)
+            return null;
+        return (amountAfterBridgeFee * (percentFee ?? 0n)) / exports.oneEther;
+    }
+    else if (feeType === fee_type_js_1.FeeType.GAS_TIP) {
+        return limit;
+    }
+    else if (feeType === fee_type_js_1.FeeType.FIXED) {
+        return fixedFee ?? 0n;
+    }
+    return 0n;
+};
+exports.availableCompensationMaximum = availableCompensationMaximum;
+/**
+ * Determines if the bridge is undercompensated based on network costs vs compensation limit using desired compensation rate
+ * @param estimatedTokenNetworkCost - the estimated token network cost
+ * @param feeType - the fee type
+ * @param limit - the maximum compensation limit
+ * @param amountAfterBridgeFee - the amount after bridge fee
+ * @param desiredExcessCompensationBasisPoints - the desired excess compensation basis points
+ * @returns whether the bridge is undercompensated
+ */
+const isUndercompensated = ({ estimatedTokenNetworkCost, feeType, limit, amountAfterBridgeFee, desiredExcessCompensationBasisPoints, }) => {
+    // No undercompensation if no amount to bridge
+    if (!amountAfterBridgeFee || amountAfterBridgeFee <= 0n) {
+        return false;
+    }
+    // GAS_TIP fee type doesn't have undercompensation issues
+    if (feeType === fee_type_js_1.FeeType.GAS_TIP) {
+        return false;
+    }
+    // No network cost estimate means we can't determine undercompensation
+    if (!estimatedTokenNetworkCost) {
+        return false;
+    }
+    // Calculate desired compensation using the actual desired compensation ratio
+    const desiredCompensationRatio = exports.oneEther + (desiredExcessCompensationBasisPoints * exports.oneEther) / exports.basisPoints;
+    const desiredCompensationForNetworkCost = (estimatedTokenNetworkCost * desiredCompensationRatio) / exports.oneEther;
+    // Undercompensated if desired compensation exceeds the limit
+    return desiredCompensationForNetworkCost > limit;
+};
+exports.isUndercompensated = isUndercompensated;
+/**
+ * Why a bridge key must not be built into a transaction for the pair on screen,
+ * or null when the two agree.
+ *
+ * WHY THIS EXISTS, in the reader's words: "i just tried to swap from weth from
+ * ethereum on pls, to pls, and the calldata that i must have signed was to
+ * bridge back from pls to eth". A selection of PulseChain on BOTH sides is a
+ * swap; it has no pathway, so the bridge key kept whatever crossing it last
+ * held — or the address bar was repaired to a crossing — and the settings
+ * cascade went on building a real, signable transfer of the reader's bridged
+ * wrapped ether to Ethereum while the screen still named PulseChain.
+ *
+ * Three refusals, and each one is a separate way the two can part company:
+ *
+ * - A SAME-CHAIN SELECTION IS NEVER A CROSSING. Origin and destination on one
+ *   chain describes a swap. No omnibridge pathway can serve it, so any pathway
+ *   reached for here belongs to some other journey.
+ * - THE PATHWAY MUST LEAVE THE CHAIN THE READER'S FUNDS ARE ON. A key whose
+ *   source chain differs spends a token the reader is not looking at.
+ * - THE PATHWAY MUST LAND WHERE THE READER ASKED. This is the reported defect:
+ *   the destination silently became Ethereum.
+ *
+ * `signedCrossing` is `null` for a call no reader composed — the aggregator's
+ * executor call built by `buildDestinationCalldata`, where the chain pair IS
+ * the pathway and there is no screen to disagree with. Nullable rather than
+ * optional so every caller has to decide, and the decision is visible at the
+ * call site.
+ *
+ * @param bridgeKey - the key the pathway was resolved from
+ * @param signedCrossing - the pair on screen, or null when no surface composed it
+ * @returns the reason to refuse, or null when the two agree
+ */
+const crossingRefusal = ({ bridgeKey, signedCrossing, }) => {
+    // `undefined` is treated as `null` here, and only here. The field is REQUIRED
+    // by the type, so no compiled caller can omit it — but a test double that
+    // returns a partial object can, and a crash inside the settings cascade blanks
+    // the page rather than refusing a transaction.
+    if (signedCrossing === null || signedCrossing === undefined) {
+        return null;
+    }
+    const { originChainId, destinationChainId } = signedCrossing;
+    if (originChainId === destinationChainId) {
+        return `Refusing to build a crossing for a selection that stays on chain ${originChainId}. Origin and destination are the same chain, which is a swap, not a bridge.`;
+    }
+    if (!bridgeKey) {
+        return `Refusing to build a crossing from chain ${originChainId} to chain ${destinationChainId}: no bridge key was resolved for it.`;
+    }
+    const pathwayOriginChainId = Number(bridgeKey[1]);
+    const pathwayDestinationChainId = Number(bridgeKey[2]);
+    if (pathwayOriginChainId !== originChainId) {
+        return `Refusing to build a crossing that leaves chain ${pathwayOriginChainId} while the selection starts on chain ${originChainId}.`;
+    }
+    if (pathwayDestinationChainId !== destinationChainId) {
+        return `Refusing to build a crossing that delivers on chain ${pathwayDestinationChainId} while the selection asks for chain ${destinationChainId}.`;
+    }
+    return null;
+};
+exports.crossingRefusal = crossingRefusal;
+/**
+ * Throws when the bridge key and the pair on screen describe different journeys.
+ *
+ * The LOUD half of {@link crossingRefusal}. {@link transactionInputs} runs
+ * during render, where a throw would blank the application, so it refuses
+ * quietly by returning null and the button it feeds stays inert. This is for
+ * the broadcast funnel, where a disagreement means something reconstructed the
+ * call another way and the reader is one signature from a transfer they never
+ * asked for — there, silence is the worse failure.
+ *
+ * @param bridgeKey - the key the pathway was resolved from
+ * @param signedCrossing - the pair on screen, or null when no surface composed it
+ * @throws when the two describe different journeys
+ */
+const assertCrossingAgrees = ({ bridgeKey, signedCrossing, }) => {
+    const refusal = (0, exports.crossingRefusal)({ bridgeKey, signedCrossing });
+    if (refusal !== null) {
+        throw new Error(refusal);
+    }
+};
+exports.assertCrossingAgrees = assertCrossingAgrees;
+/**
+ * Why a same-chain PulseX swap transaction must not be built for the leg on
+ * screen, or null when they agree. The swap-side sibling of
+ * {@link crossingRefusal}.
+ *
+ * Two refusals, each a separate way the two can part company:
+ *
+ * - THE LEG ON SCREEN NAMES A CROSSING. A caller building a swap transaction
+ *   while the reader is looking at a two-chain crossing would sign the wrong
+ *   kind of thing for what is on screen.
+ * - THE SWAP DOES NOT EXECUTE ON THE CHAIN THE READER IS LOOKING AT. A stale
+ *   candidate built for a chain the address bar has since left.
+ *
+ * @param signedLeg - what the surface believes this signature does, or null
+ *   when no surface composed it
+ * @param chainId - the chain the candidate swap transaction actually executes on
+ * @returns the reason to refuse, or null when the two agree
+ */
+const swapRefusal = ({ signedLeg, chainId, }) => {
+    // `undefined` treated as `null`, matching `crossingRefusal`'s own guard: the
+    // field is required by the type, so only a test double or a crash inside the
+    // cascade could omit it.
+    if (signedLeg === null || signedLeg === undefined) {
+        return null;
+    }
+    if (signedLeg.kind !== 'swap') {
+        return `Refusing to build a same-chain swap for a selection that names a ${signedLeg.kind} (chain ${signedLeg.originChainId} to chain ${signedLeg.destinationChainId}).`;
+    }
+    if (chainId === null) {
+        return `Refusing to build a same-chain swap: no chain was resolved for it.`;
+    }
+    if (signedLeg.chainId !== chainId) {
+        return `Refusing to build a swap on chain ${chainId} while the selection names chain ${signedLeg.chainId}.`;
+    }
+    return null;
+};
+exports.swapRefusal = swapRefusal;
+/**
+ * Throws when the leg on screen and the candidate swap transaction describe
+ * different journeys. The swap-side sibling of {@link assertCrossingAgrees} —
+ * loud where {@link swapRefusal} is quiet, for the same reason: this runs one
+ * step before the wallet, where silence is what lets a reader sign.
+ *
+ * @param signedLeg - what the surface believes this signature does, or null
+ * @param chainId - the chain the candidate swap transaction actually executes on
+ * @throws when the two describe different journeys
+ */
+const assertSwapAgrees = ({ signedLeg, chainId, }) => {
+    const refusal = (0, exports.swapRefusal)({ signedLeg, chainId });
+    if (refusal !== null) {
+        throw new Error(refusal);
+    }
+};
+exports.assertSwapAgrees = assertSwapAgrees;
+/**
+ * Why a candidate must not be signed for the leg and section a caller is
+ * about to build calldata for, or null when they agree. The candidate-pick
+ * sibling of {@link crossingRefusal}/{@link swapRefusal}.
+ *
+ * UNLIKE THOSE TWO, A MISSING PICK IS ITSELF A REFUSAL. `crossingRefusal` and
+ * `swapRefusal` let a null leg through because some calls compose no screen at
+ * all (the aggregator's own executor call). A candidate-signing sender always
+ * has a screen — the route the reader picked — so a candidate id with no
+ * recorded leg is exactly the gap this type exists to close: `candidateId`
+ * alone used to be treated as sufficient identity, and this function is what
+ * stops it from being treated that way again.
+ *
+ * @param pick - what the route recorded it picked, or null/undefined when the
+ *   producer that built the route never set one
+ * @param leg - the leg the caller is about to build calldata for
+ * @param sectionIndex - the route section the caller is about to build
+ *   calldata for
+ * @returns the reason to refuse, or null when they agree
+ */
+const candidatePickRefusal = ({ pick, leg, sectionIndex, }) => {
+    if (pick === null || pick === undefined) {
+        return `Refusing to sign a ${leg} at section ${sectionIndex}: the route named no candidate to sign.`;
+    }
+    if (pick.leg !== leg) {
+        return `Refusing to sign candidate ${pick.candidateId}'s ${pick.leg} leg as a ${leg}: the route picked a different kind of leg.`;
+    }
+    if (pick.sectionIndex !== sectionIndex) {
+        return `Refusing to sign candidate ${pick.candidateId} for section ${sectionIndex}: the route picked it for section ${pick.sectionIndex}.`;
+    }
+    return null;
+};
+exports.candidatePickRefusal = candidatePickRefusal;
+/**
+ * Throws when a candidate pick and the leg/section a caller is about to build
+ * calldata for describe different signatures. The candidate-pick sibling of
+ * {@link assertCrossingAgrees}/{@link assertSwapAgrees} — loud where {@link
+ * candidatePickRefusal} is quiet, for the same reason: this runs one step
+ * before the wallet, where silence is what lets a reader sign the wrong thing.
+ *
+ * @param pick - what the route recorded it picked, or null
+ * @param leg - the leg the caller is about to build calldata for
+ * @param sectionIndex - the route section the caller is about to build
+ *   calldata for
+ * @throws when the pick and the leg/section being built describe different
+ *   signatures
+ */
+const assertCandidatePickAgrees = ({ pick, leg, sectionIndex, }) => {
+    const refusal = (0, exports.candidatePickRefusal)({ pick, leg, sectionIndex });
+    if (refusal !== null) {
+        throw new Error(refusal);
+    }
+};
+exports.assertCandidatePickAgrees = assertCandidatePickAgrees;
+/**
+ * Calculates the same-chain PulseX swap transaction inputs, or null when the
+ * inputs cannot form a call — including when the leg on screen and the swap's
+ * own chain disagree. The swap-side sibling of {@link transactionInputs}.
+ *
+ * SAME SHAPE AS `transactionInputs`, deliberately: `{ to, value, data } | null`,
+ * so a caller can dispatch either builder's result through one `sendTransaction`
+ * without a second shape to handle.
+ *
+ * WRAPPING AND UNWRAPPING THE NATIVE COIN USE THE ROUTER'S OWN NATIVE-COIN
+ * FUNCTIONS, not a separate deposit/withdraw step — one router contract wraps
+ * on the way in (`swapExactETHForTokens`) and unwraps on the way out
+ * (`swapExactTokensForETH`), the same contract `swapExactTokensForTokens`
+ * already targets when neither side is native.
+ *
+ * @param signedLeg - what the surface believes this signature does, or null
+ * @param chainId - the chain the swap actually executes on
+ * @param routerAddress - the PulseX router this swap is sent to, or null when
+ *   none is deployed for this chain
+ * @param fromTokenAddress - the input token address, or the zero address for
+ *   the chain's native coin
+ * @param toTokenAddress - the output token address, or the zero address for
+ *   the chain's native coin
+ * @param swapPath - the ordered swap path — for a route-search hop, the one
+ *   its quote was priced along (`pulseXSwapPathForHop`),
+ *   already expressed in the router's own token addresses — the wrapped-native
+ *   token stands in for either native end
+ * @param amountIn - the amount to swap, in the input token's base units
+ * @param minAmountOut - the minimum acceptable output after slippage, in the
+ *   output token's base units
+ * @param recipient - the address the swap delivers to
+ * @param deadline - the unix-seconds deadline the router enforces
+ * @returns the transaction inputs, or null when the inputs cannot form a call
+ */
+const pulseXSwapTransactionInputs = ({ signedLeg, chainId, routerAddress, fromTokenAddress, toTokenAddress, swapPath, amountIn, minAmountOut, recipient, deadline, }) => {
+    // FIRST, BEFORE ANY ENCODING — see `transactionInputs`'s identical note.
+    if ((0, exports.swapRefusal)({ signedLeg, chainId }) !== null) {
+        return null;
+    }
+    if (!routerAddress) {
+        return null;
+    }
+    if (!recipient || !(0, viem_1.isAddress)(recipient) || recipient === viem_1.zeroAddress) {
+        return null;
+    }
+    if (swapPath.length < 2) {
+        return null;
+    }
+    if (amountIn <= 0n) {
+        return null;
+    }
+    const fromIsNative = fromTokenAddress === viem_1.zeroAddress;
+    const toIsNative = toTokenAddress === viem_1.zeroAddress;
+    // Native-to-native names no real swap — there is nothing for the router to do.
+    if (fromIsNative && toIsNative) {
+        return null;
+    }
+    if (fromIsNative) {
+        return {
+            to: routerAddress,
+            value: amountIn,
+            data: (0, viem_1.encodeFunctionData)({
+                abi: abis.univ2Router,
+                functionName: 'swapExactETHForTokens',
+                args: [minAmountOut, swapPath, recipient, deadline],
+            }),
+        };
+    }
+    if (toIsNative) {
+        return {
+            to: routerAddress,
+            value: 0n,
+            data: (0, viem_1.encodeFunctionData)({
+                abi: abis.univ2Router,
+                functionName: 'swapExactTokensForETH',
+                args: [amountIn, minAmountOut, swapPath, recipient, deadline],
+            }),
+        };
+    }
+    return {
+        to: routerAddress,
+        value: 0n,
+        data: (0, viem_1.encodeFunctionData)({
+            abi: abis.univ2Router,
+            functionName: 'swapExactTokensForTokens',
+            args: [amountIn, minAmountOut, swapPath, recipient, deadline],
+        }),
+    };
+};
+exports.pulseXSwapTransactionInputs = pulseXSwapTransactionInputs;
+/**
+ * Calculates the transaction inputs from the bridge pathway, asset in, recipient, account, asset link, destination data param, amount to bridge, fee director struct encoded, and should deliver
+ * @param bridgeKey - the key the pathway was resolved from, for {@link crossingRefusal}
+ * @param signedCrossing - the chain pair on screen, or null when no surface composed it
+ * @param bridgePathway - the bridge pathway to use
+ * @param assetIn - the asset in to bridge
+ * @param recipient - the recipient of the bridge
+ * @param account - the account to bridge from
+ * @param assetLink - the asset link to use
+ * @param destinationDataParam - the destination data param to use
+ * @param amountToBridge - the amount to bridge
+ * @param feeDirectorStructEncoded - the fee director struct encoded to use
+ * @param shouldDeliver - whether to deliver the tokens to the recipient
+ * @returns the transaction inputs, or null when the inputs cannot form a call —
+ *   including when the pathway crosses somewhere other than the pair on screen
+ */
+const transactionInputs = ({ bridgeKey, signedCrossing, bridgePathway, assetIn, recipient, account, assetLink, destinationDataParam, amountToBridge, feeDirectorStructEncoded, shouldDeliver, }) => {
+    // FIRST, BEFORE ANY ENCODING. Every branch below writes a real mediator call;
+    // by the time one is chosen the disagreement is already encoded.
+    if ((0, exports.crossingRefusal)({ bridgeKey, signedCrossing }) !== null) {
+        return null;
+    }
+    if (!bridgePathway) {
+        return null;
+    }
+    // check that recipient is valid
+    if (!recipient || !(0, viem_1.isAddress)(recipient) || recipient === viem_1.zeroAddress) {
+        return null;
+    }
+    // check that wallet account is valid
+    if (!account || !(0, viem_1.isAddress)(account) || account === viem_1.zeroAddress) {
+        return null;
+    }
+    // check that asset in is valid
+    if (!assetIn) {
+        return null;
+    }
+    // check that asset link is valid
+    if (!assetLink) {
+        return null;
+    }
+    let value = 0n;
+    // we are moving "from" this side, so we need to call a function on the "from" address
+    // only relevant for the relayTokens(AndCall) pathway outside of native tokens
+    let toAddress = bridgePathway.from;
+    let data = '0x';
+    const inputIsBridgeToken = (0, exports.interactingWithBridgeToken)({
+        assetLink,
+        assetInAddress: assetIn.address,
+    });
+    if (inputIsBridgeToken) {
+        // when interacting with a bridged token, we need to call the token address directly
+        toAddress = assetIn.address;
+        value = 0n;
+        // if we want delivery of the tokens (going from home to foreign) then we need to have the foreign data param
+        // and it needs to start with the destination router
+        if (!destinationDataParam) {
+            return null;
+        }
+        data = bridgePathway.usesExtraParam
+            ? (0, viem_1.encodeFunctionData)({
+                abi: abis.erc677ExtraInput,
+                functionName: 'transferAndCall',
+                args: [bridgePathway.from, amountToBridge, destinationDataParam, account],
+            })
+            : (0, viem_1.encodeFunctionData)({
+                abi: abis.erc677,
+                functionName: 'transferAndCall',
+                args: [bridgePathway.from, amountToBridge, destinationDataParam],
+            });
+    }
+    else if (assetIn.address === viem_1.zeroAddress) {
+        value = amountToBridge;
+        toAddress = bridgePathway.nativeRouter;
+        if (bridgePathway.feeManager === 'from' && shouldDeliver) {
+            // transferring native to foreign
+            if (!feeDirectorStructEncoded)
+                return null;
+            if (!bridgePathway.destinationRouter)
+                return null;
+            data = bridgePathway.usesExtraParam
+                ? (0, viem_1.encodeFunctionData)({
+                    abi: abis.nativeRouterExtraInput,
+                    functionName: 'relayTokensAndCall',
+                    args: [bridgePathway.destinationRouter, feeDirectorStructEncoded, account],
+                })
+                : (0, viem_1.encodeFunctionData)({
+                    abi: abis.nativeRouter,
+                    functionName: 'relayTokensAndCall',
+                    args: [bridgePathway.destinationRouter, feeDirectorStructEncoded],
+                });
+        }
+        else {
+            // delivery always occurs when moving from foreign to home
+            data = bridgePathway.usesExtraParam
+                ? (0, viem_1.encodeFunctionData)({
+                    abi: abis.nativeRouterExtraInput,
+                    functionName: 'wrapAndRelayTokens',
+                    args: [recipient, account],
+                })
+                : (0, viem_1.encodeFunctionData)({
+                    abi: abis.nativeRouter,
+                    functionName: 'wrapAndRelayTokens',
+                    args: [recipient],
+                });
+        }
+    }
+    else {
+        // tokens native to this side, entering the bridge
+        if (shouldDeliver && bridgePathway.requiresDelivery) {
+            if (!feeDirectorStructEncoded)
+                return null;
+            if (!bridgePathway.destinationRouter)
+                return null;
+            data = bridgePathway.usesExtraParam
+                ? (0, viem_1.encodeFunctionData)({
+                    abi: abis.inputBridgeExtraInput,
+                    functionName: 'relayTokensAndCall',
+                    args: [
+                        assetIn.address,
+                        bridgePathway.destinationRouter,
+                        amountToBridge,
+                        feeDirectorStructEncoded,
+                        account,
+                    ],
+                })
+                : (0, viem_1.encodeFunctionData)({
+                    abi: abis.inputBridge,
+                    functionName: 'relayTokensAndCall',
+                    args: [
+                        assetIn.address,
+                        bridgePathway.destinationRouter,
+                        amountToBridge,
+                        feeDirectorStructEncoded,
+                    ],
+                });
+        }
+        else {
+            data = bridgePathway.usesExtraParam
+                ? (0, viem_1.encodeFunctionData)({
+                    abi: abis.inputBridgeExtraInput,
+                    functionName: 'relayTokens',
+                    args: [assetIn.address, recipient, amountToBridge, account],
+                })
+                : (0, viem_1.encodeFunctionData)({
+                    abi: abis.inputBridge,
+                    functionName: 'relayTokens',
+                    args: [assetIn.address, recipient, amountToBridge],
+                });
+        }
+    }
+    return {
+        to: toAddress,
+        value,
+        data,
+    };
+};
+exports.transactionInputs = transactionInputs;
+/**
+ * Calculates the asset out key from the bridge key path, asset in address, and unwrap
+ * @param bridgeKeyPath - the bridge key path
+ * @param assetInAddress - the asset in address
+ * @param unwrap - whether to unwrap
+ * @returns the asset out key
+ */
+const assetOutKey = ({ bridgeKeyPath, assetInAddress, unwrap, }) => {
+    if (!bridgeKeyPath || !assetInAddress)
+        return null;
+    return `${bridgeKeyPath}/${unwrap ? 'native' : 'erc20'}/${assetInAddress.toLowerCase()}`;
+};
+exports.assetOutKey = assetOutKey;
+/**
+ * Returns the asset out from the asset in address, assets out, bridge key path, and unwrap
+ * @param assetInAddress - the asset in address
+ * @param assetsOut - the assets out
+ * @param bridgeKeyPath - the bridge key path
+ * @param unwrap - whether to unwrap
+ * @returns the asset out
+ */
+const assetOut = ({ assetInAddress, assetsOut, bridgeKeyPath, unwrap, }) => {
+    if (!assetInAddress)
+        return null;
+    const key = (0, exports.assetOutKey)({
+        bridgeKeyPath,
+        assetInAddress,
+        unwrap,
+    });
+    if (!key)
+        return null;
+    return assetsOut.get(key) ?? null;
+};
+exports.assetOut = assetOut;