@gibs/bridge-sdk 1.19.0 → 1.20.0

package/dist/settings.js

@@ -4,43 +4,18 @@ import { isNative, nativeAssetOut, pathway } from './config.js';
 import { FeeType } from './fee-type.js';
 export const oneEther = 10n ** 18n;
 export const 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
- */
 export const bridgePathway = ({ bridgeKey, isProd, assetIn, }) => pathway(bridgeKey, isProd, assetIn?.address) ?? null;
-/**
- * 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
- */
 export const amountToBridge = ({ amountIn, assetIn, }) => {
     if (!amountIn || amountIn === 0n || !assetIn) {
         return 0n;
     }
     return amountIn;
 };
-/**
- * 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
- */
 export const bridgeCost = ({ amountToBridge, bridgeFee, }) => {
     if (bridgeFee === null)
         return null;
     return (amountToBridge * bridgeFee) / oneEther;
 };
-/**
- * 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
- */
 export const amountAfterBridgeFee = ({ amountToBridge, bridgeCost, }) => {
     if (bridgeCost === null)
         return null;
@@ -49,12 +24,6 @@ export const amountAfterBridgeFee = ({ amountToBridge, bridgeCost, }) => {
         return 0n;
     return afterFee;
 };
-/**
- * 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
- */
 export const estimatedAmountOut = ({ amountAfterBridgeFee, fee, }) => {
     if (typeof fee !== 'bigint')
         return null;
@@ -64,16 +33,6 @@ export const estimatedAmountOut = ({ amountAfterBridgeFee, fee, }) => {
         return 0n;
     return amountAfterBridgeFee - fee;
 };
-/**
- * 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
- */
 export const estimatedFee = ({ amountAfterBridgeFee, fee, percentFee, feeType, limit, costsToDeliver, }) => {
     const fixedFee = amountAfterBridgeFee ? (amountAfterBridgeFee * percentFee) / oneEther : null;
     if (!costsToDeliver) {
@@ -92,28 +51,12 @@ export const estimatedFee = ({ amountAfterBridgeFee, fee, percentFee, feeType, l
     }
     return null;
 };
-/**
- * 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
- */
 export const estimatedNativeNetworkCost = ({ estimatedGas, latestBaseFeePerGas, requiresDelivery, }) => {
     if (!estimatedGas || !latestBaseFeePerGas || !requiresDelivery) {
         return null;
     }
     return BigInt(estimatedGas * latestBaseFeePerGas);
 };
-/**
- * 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
- */
 export const estimatedTokenNetworkCost = ({ estimatedNativeNetworkCost, priceCorrective, decimals, oneTokenInt, }) => {
     if (!priceCorrective || !oneTokenInt || !estimatedNativeNetworkCost || !decimals) {
         return null;
@@ -121,56 +64,26 @@ export const estimatedTokenNetworkCost = ({ estimatedNativeNetworkCost, priceCor
     const tokenCost = (estimatedNativeNetworkCost * oneTokenInt) / priceCorrective;
     return tokenCost;
 };
-/**
- * Calculates one token of the asset in as an int
- * @param assetIn - the asset in to bridge
- * @returns the one token int
- */
 export const oneTokenInt = ({ assetIn }) => {
     if (!assetIn)
         return 1n;
     return 10n ** BigInt(assetIn.decimals);
 };
-/**
- * Returns the limit as a bigint. Nil uses 0n
- * @param lim - the limit
- * @returns the limit
- */
 export const limit = (lim) => {
     if (!lim) {
         return 0n;
     }
     return lim;
 };
-/**
- * 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
- */
 export const networkSwitchAssetOutAddress = ({ assetOut, unwrap, toChain, }) => {
     if (!assetOut)
         return null;
     if (!unwrap)
         return assetOut.address;
     const wrappedNative = 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 && isAddress(assetOut.address, { strict: false }) && isAddressEqual(wrappedNative, assetOut.address);
     return isWrappedNative ? zeroAddress : assetOut.address;
 };
-/**
- * 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
- */
 export const desiredExcessCompensationBasisPoints = ({ path, assetIn, assetOut, bridgeKey, feeType, list, assetOutAddress, }) => {
     if (!path?.requiresDelivery) {
         return 0n;
@@ -186,31 +99,6 @@ export const desiredExcessCompensationBasisPoints = ({ path, assetIn, assetOut,
                     ? 5000n
                     : 10000n;
 };
-/**
- * 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
- */
 export const deliveryFee = ({ shouldDeliver, routeOffersDelivery, feeType, amountAfterBridgeFee, percentFee, fixedFee, limit, }) => {
     if (!shouldDeliver || !routeOffersDelivery) {
         return { status: 'not-requested' };
@@ -230,18 +118,6 @@ export const deliveryFee = ({ shouldDeliver, routeOffersDelivery, feeType, amoun
         rate: percentFee,
     };
 };
-/**
- * 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}
- */
 export const feeTypeSettings = ({ feeType, unwrap }) => {
     const fixedBit = feeType === FeeType.FIXED ? 1n : 0n;
     const unwrapBit = unwrap ? 1n : 0n;
@@ -249,42 +125,11 @@ export const feeTypeSettings = ({ feeType, unwrap }) => {
     const percentBit = feeType === FeeType.PERCENT ? 1n : 0n;
     return (percentBit << 3n) | (excludePriorityBit << 2n) | (unwrapBit << 1n) | fixedBit;
 };
-/**
- * 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
- */
 export const approveCall = ({ token, spender, amount, }) => ({
     to: token,
     value: 0n,
     data: encodeFunctionData({ abi: erc20Abi, functionName: 'approve', args: [spender, amount] }),
 });
-/**
- * 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]`
- */
 export const approvalAmounts = ({ allowance, minimum, }) => {
     if (allowance >= minimum)
         return [];
@@ -292,21 +137,6 @@ export const approvalAmounts = ({ allowance, minimum, }) => {
         return [minimum];
     return [0n, minimum];
 };
-/**
- * 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
- */
 export const omnibridgeApproval = ({ bridgePathway, assetIn, assetLink, amountToBridge, }) => {
     if (assetIn.address === zeroAddress)
         return null;
@@ -319,34 +149,16 @@ export const omnibridgeApproval = ({ bridgePathway, assetIn, assetLink, amountTo
         minimum: amountToBridge,
     };
 };
-/**
- * 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
- */
 export const reasonableFixedFee = ({ estimatedTokenNetworkCost, desiredExcessCompensationBasisPoints, }) => {
     if (!estimatedTokenNetworkCost) {
         return null;
     }
     return ((estimatedTokenNetworkCost * (25000n + desiredExcessCompensationBasisPoints)) / basisPoints);
 };
-/**
- * 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
- */
 export const reasonablePercentOnGasLimit = ({ gasTipFee, estimatedTokenNetworkCost, }) => {
     return ((25000n * ((oneEther + (gasTipFee ?? 0n)) * (estimatedTokenNetworkCost ?? 0n))) /
         (oneEther * basisPoints));
 };
-/**
- * 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
- */
 export const reasonablePercentFee = ({ reasonableFixedFee, amountAfterBridgeFee, }) => {
     if (!reasonableFixedFee) {
         return null;
@@ -359,7 +171,7 @@ export const reasonablePercentFee = ({ reasonableFixedFee, amountAfterBridgeFee,
     const max = 1000n * basisFeeTruncator;
     const min = 5n * basisFeeTruncator;
     if (highFee < reasonableFixedFee) {
-        return max; // 10%
+        return max;
     }
     const highResPercent = (reasonableFixedFee * oneEther) / amountAfterBridgeFee;
     if (highResPercent < min) {
@@ -371,12 +183,6 @@ export const reasonablePercentFee = ({ reasonableFixedFee, amountAfterBridgeFee,
     const basisPoint = highResPercent / basisFeeTruncator;
     return basisPoint * basisFeeTruncator;
 };
-/**
- * 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
- */
 export const interactingWithBridgeToken = ({ assetLink, assetInAddress, }) => {
     const { toForeign, toHome } = assetLink || {};
     const { foreign } = toForeign || {};
@@ -386,19 +192,6 @@ export const interactingWithBridgeToken = ({ assetLink, assetInAddress, }) => {
     return !!((foreign && getAddress(foreign) === getAddress(assetInAddress)) ||
         (home && getAddress(home) === getAddress(assetInAddress)));
 };
-/**
- * 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
- */
 export const feeDirectorStructEncoded = ({ recipient, bridgePathway, feeType, priceCorrective, gasTipFee, percentFee, feeTypeSettings, limit, assetOut, }) => {
     if (!assetOut || !bridgePathway) {
         return null;
@@ -424,20 +217,7 @@ export const feeDirectorStructEncoded = ({ recipient, bridgePathway, feeType, pr
         [recipient, feeTypeSettings, limit, multiplier],
     ]);
 };
-/**
- * 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
- */
 export const destinationDataParam = ({ recipient, bridgePathway, assetIn, destinationRouter, feeDirectorStructEncoded, assetLink, shouldDeliver, unwrap, }) => {
-    // const recipient = input.recipient.value
     if (!recipient) {
         return null;
     }
@@ -447,8 +227,6 @@ export const destinationDataParam = ({ recipient, bridgePathway, assetIn, destin
     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;
     }
@@ -456,12 +234,9 @@ export const destinationDataParam = ({ recipient, bridgePathway, assetIn, destin
         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 concatHex([destinationRouter, feeDirectorStructEncoded]);
         }
@@ -470,34 +245,14 @@ export const destinationDataParam = ({ recipient, bridgePathway, assetIn, destin
     if (!unwrap) {
         return recipient;
     }
-    // unwrap wpls->pls
     return concatHex([destinationRouter, recipient]);
 };
-/**
- * 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
- */
 export const reasonablePercentOnTopOfGasFee = ({ desiredExcessCompensationBasisPoints, }) => {
     return desiredExcessCompensationBasisPoints * (oneEther / basisPoints);
 };
-/**
- * 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
- */
 export const desiredCompensationRatio = ({ desiredExcessCompensationBasisPoints, }) => {
     return oneEther + (desiredExcessCompensationBasisPoints * oneEther) / basisPoints;
 };
-/**
- * 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
- */
 export const availableCompensationMaximum = ({ amountAfterBridgeFee, percentFee, feeType, fixedFee, limit, }) => {
     if (feeType === FeeType.PERCENT) {
         if (amountAfterBridgeFee === null)
@@ -512,71 +267,21 @@ export const availableCompensationMaximum = ({ amountAfterBridgeFee, percentFee,
     }
     return 0n;
 };
-/**
- * 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
- */
 export 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 === 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 = oneEther + (desiredExcessCompensationBasisPoints * oneEther) / basisPoints;
     const desiredCompensationForNetworkCost = (estimatedTokenNetworkCost * desiredCompensationRatio) / oneEther;
-    // Undercompensated if desired compensation exceeds the limit
     return desiredCompensationForNetworkCost > limit;
 };
-/**
- * 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
- */
 export 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;
     }
@@ -597,48 +302,13 @@ export const crossingRefusal = ({ bridgeKey, signedCrossing, }) => {
     }
     return null;
 };
-/**
- * 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
- */
 export const assertCrossingAgrees = ({ bridgeKey, signedCrossing, }) => {
     const refusal = crossingRefusal({ bridgeKey, signedCrossing });
     if (refusal !== null) {
         throw new Error(refusal);
     }
 };
-/**
- * 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
- */
 export 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;
     }
@@ -653,42 +323,12 @@ export const swapRefusal = ({ signedLeg, chainId, }) => {
     }
     return null;
 };
-/**
- * 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
- */
 export const assertSwapAgrees = ({ signedLeg, chainId, }) => {
     const refusal = swapRefusal({ signedLeg, chainId });
     if (refusal !== null) {
         throw new Error(refusal);
     }
 };
-/**
- * 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
- */
 export 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.`;
@@ -701,62 +341,13 @@ export const candidatePickRefusal = ({ pick, leg, sectionIndex, }) => {
     }
     return null;
 };
-/**
- * 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
- */
 export const assertCandidatePickAgrees = ({ pick, leg, sectionIndex, }) => {
     const refusal = candidatePickRefusal({ pick, leg, sectionIndex });
     if (refusal !== null) {
         throw new Error(refusal);
     }
 };
-/**
- * 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
- */
 export const pulseXSwapTransactionInputs = ({ signedLeg, chainId, routerAddress, fromTokenAddress, toTokenAddress, swapPath, amountIn, minAmountOut, recipient, deadline, }) => {
-    // FIRST, BEFORE ANY ENCODING — see `transactionInputs`'s identical note.
     if (swapRefusal({ signedLeg, chainId }) !== null) {
         return null;
     }
@@ -774,7 +365,6 @@ export const pulseXSwapTransactionInputs = ({ signedLeg, chainId, routerAddress,
     }
     const fromIsNative = fromTokenAddress === zeroAddress;
     const toIsNative = toTokenAddress === zeroAddress;
-    // Native-to-native names no real swap — there is nothing for the router to do.
     if (fromIsNative && toIsNative) {
         return null;
     }
@@ -810,50 +400,26 @@ export const pulseXSwapTransactionInputs = ({ signedLeg, chainId, routerAddress,
         }),
     };
 };
-/**
- * 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
- */
 export 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 (crossingRefusal({ bridgeKey, signedCrossing }) !== null) {
         return null;
     }
     if (!bridgePathway) {
         return null;
     }
-    // check that recipient is valid
     if (!recipient || !isAddress(recipient) || recipient === zeroAddress) {
         return null;
     }
-    // check that wallet account is valid
     if (!account || !isAddress(account) || account === 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 = interactingWithBridgeToken({
@@ -861,11 +427,8 @@ export const transactionInputs = ({ bridgeKey, signedCrossing, bridgePathway, as
         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;
         }
@@ -885,7 +448,6 @@ export const transactionInputs = ({ bridgeKey, signedCrossing, bridgePathway, as
         value = amountToBridge;
         toAddress = bridgePathway.nativeRouter;
         if (bridgePathway.feeManager === 'from' && shouldDeliver) {
-            // transferring native to foreign
             if (!feeDirectorStructEncoded)
                 return null;
             if (!bridgePathway.destinationRouter)
@@ -903,7 +465,6 @@ export const transactionInputs = ({ bridgeKey, signedCrossing, bridgePathway, as
                 });
         }
         else {
-            // delivery always occurs when moving from foreign to home
             data = bridgePathway.usesExtraParam
                 ? encodeFunctionData({
                     abi: abis.nativeRouterExtraInput,
@@ -918,7 +479,6 @@ export const transactionInputs = ({ bridgeKey, signedCrossing, bridgePathway, as
         }
     }
     else {
-        // tokens native to this side, entering the bridge
         if (shouldDeliver && bridgePathway.requiresDelivery) {
             if (!feeDirectorStructEncoded)
                 return null;
@@ -967,26 +527,11 @@ export const transactionInputs = ({ bridgeKey, signedCrossing, bridgePathway, as
         data,
     };
 };
-/**
- * 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
- */
 export const assetOutKey = ({ bridgeKeyPath, assetInAddress, unwrap, }) => {
     if (!bridgeKeyPath || !assetInAddress)
         return null;
     return `${bridgeKeyPath}/${unwrap ? 'native' : 'erc20'}/${assetInAddress.toLowerCase()}`;
 };
-/**
- * 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
- */
 export const assetOut = ({ assetInAddress, assetsOut, bridgeKeyPath, unwrap, }) => {
     if (!assetInAddress)
         return null;