@gibs/bridge-sdk 1.10.1 → 1.13.0

package/dist/{src/settings.js → settings.js}

@@ -1,7 +1,7 @@
-import { concatHex, encodeAbiParameters, encodeFunctionData, getAddress, isAddress, zeroAddress } from "viem";
-import { isNative, nativeAssetOut, pathway } from "./config.js";
-import { FeeType } from "./fee-type.js";
-import * as abis from "./abis.js";
+import { concatHex, encodeAbiParameters, encodeFunctionData, getAddress, isAddress, isAddressEqual, zeroAddress, } from 'viem';
+import * as abis from './abis.js';
+import { isNative, nativeAssetOut, pathway } from './config.js';
+import { FeeType } from './fee-type.js';
 export const oneEther = 10n ** 18n;
 export const basisPoints = 10000n;
 /**
@@ -11,7 +11,7 @@ export const basisPoints = 10000n;
  * @param assetIn - the asset in to bridge
  * @returns the bridge pathway
  */
-export const bridgePathway = ({ bridgeKey, isProd, assetIn, }) => (pathway(bridgeKey, isProd, assetIn?.address) ?? null);
+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
@@ -126,7 +126,7 @@ export const estimatedTokenNetworkCost = ({ estimatedNativeNetworkCost, priceCor
  * @param assetIn - the asset in to bridge
  * @returns the one token int
  */
-export const oneTokenInt = ({ assetIn, }) => {
+export const oneTokenInt = ({ assetIn }) => {
     if (!assetIn)
         return 1n;
     return 10n ** BigInt(assetIn.decimals);
@@ -154,7 +154,11 @@ export const networkSwitchAssetOutAddress = ({ assetOut, unwrap, toChain, }) =>
         return null;
     if (!unwrap)
         return assetOut.address;
-    return nativeAssetOut[toChain] === assetOut.address ? zeroAddress : 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
@@ -171,7 +175,7 @@ export const desiredExcessCompensationBasisPoints = ({ path, assetIn, assetOut,
     if (!path?.requiresDelivery) {
         return 0n;
     }
-    return (!assetIn
+    return !assetIn
         ? 0n
         : feeType === FeeType.PERCENT
             ? 1000n
@@ -180,36 +184,51 @@ export const desiredExcessCompensationBasisPoints = ({ path, assetIn, assetOut,
                 : list.has(getAddress(assetIn?.address ?? '')) ||
                     list.has(assetOutAddress ? getAddress(assetOutAddress) : '0x')
                     ? 5000n
-                    : 10000n);
+                    : 10000n;
 };
 /**
- * Calculates the estimated cost from the should deliver, amount after bridge fee, percent fee,
- * estimated token network cost, reasonable percent on top of gas fee, and fee type
- * @param shouldDeliver - whether to deliver the costs
- * @param amountAfterBridgeFee - the amount after bridge fee
- * @param percentFee - the percent fee
- * @param estimatedTokenNetworkCost - the estimated token network cost
- * @param reasonablePercentOnTopOfGasFee - the reasonable percent on top of gas fee
- * @param feeType - the fee type
- * @returns the estimated cost
+ * 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 estimatedCost = ({ shouldDeliver, amountAfterBridgeFee, percentFee, estimatedTokenNetworkCost, reasonablePercentOnTopOfGasFee, feeType, }) => {
-    if (!shouldDeliver) {
-        return null;
+export const deliveryFee = ({ shouldDeliver, routeOffersDelivery, feeType, amountAfterBridgeFee, percentFee, fixedFee, limit, }) => {
+    if (!shouldDeliver || !routeOffersDelivery) {
+        return { status: 'not-requested' };
     }
-    if (feeType === FeeType.PERCENT) {
-        if (amountAfterBridgeFee === null)
-            return null;
-        return (amountAfterBridgeFee * (percentFee ?? 0n)) / oneEther;
+    if (feeType === FeeType.FIXED) {
+        return { status: 'requested', amount: fixedFee, rate: null };
     }
-    // gas tip
-    if (!estimatedTokenNetworkCost) {
-        return null;
+    if (feeType === FeeType.GAS_TIP) {
+        return { status: 'requested', amount: limit, rate: null };
     }
-    if (!reasonablePercentOnTopOfGasFee) {
-        return null;
+    if (amountAfterBridgeFee === null || percentFee === null) {
+        return { status: 'requested', amount: null, rate: percentFee };
     }
-    return estimatedTokenNetworkCost * (reasonablePercentOnTopOfGasFee + oneEther);
+    return {
+        status: 'requested',
+        amount: (amountAfterBridgeFee * percentFee) / oneEther,
+        rate: percentFee,
+    };
 };
 /**
  * Calculates the reasonable fixed fee from the estimated token network cost and desired excess compensation basis points
@@ -221,8 +240,7 @@ export const reasonableFixedFee = ({ estimatedTokenNetworkCost, desiredExcessCom
     if (!estimatedTokenNetworkCost) {
         return null;
     }
-    return ((estimatedTokenNetworkCost * (25000n + desiredExcessCompensationBasisPoints)) /
-        basisPoints);
+    return ((estimatedTokenNetworkCost * (25000n + desiredExcessCompensationBasisPoints)) / basisPoints);
 };
 /**
  * Calculates the reasonable percent on gas limit from the gas tip fee and estimated token network cost
@@ -231,8 +249,7 @@ export const reasonableFixedFee = ({ estimatedTokenNetworkCost, desiredExcessCom
  * @returns the reasonable percent on gas limit
  */
 export const reasonablePercentOnGasLimit = ({ gasTipFee, estimatedTokenNetworkCost, }) => {
-    return ((25000n *
-        ((oneEther + (gasTipFee ?? 0n)) * (estimatedTokenNetworkCost ?? 0n))) /
+    return ((25000n * ((oneEther + (gasTipFee ?? 0n)) * (estimatedTokenNetworkCost ?? 0n))) /
         (oneEther * basisPoints));
 };
 /**
@@ -306,8 +323,7 @@ export const feeDirectorStructEncoded = ({ recipient, bridgePathway, feeType, pr
     let multiplier = 0n;
     if (feeType === FeeType.GAS_TIP && priceCorrective > 0n) {
         multiplier =
-            ((oneEther + (gasTipFee ?? 0n)) * 10n ** BigInt(assetOut.decimals)) /
-                priceCorrective;
+            ((oneEther + (gasTipFee ?? 0n)) * 10n ** BigInt(assetOut.decimals)) / priceCorrective;
     }
     else if (feeType === FeeType.PERCENT) {
         multiplier = percentFee ?? 0n;
@@ -340,15 +356,12 @@ export const destinationDataParam = ({ recipient, bridgePathway, assetIn, destin
         return null;
     }
     if (!destinationRouter) {
-        console.log('no destination router');
         return null;
     }
     if (bridgePathway.requiresDelivery && !feeDirectorStructEncoded) {
-        console.log('no fee director struct encoded');
         return null;
     }
     if (!assetLink) {
-        console.log('no asset link');
         return null;
     }
     if (bridgePathway.requiresDelivery) {
@@ -375,7 +388,7 @@ export const destinationDataParam = ({ recipient, bridgePathway, assetIn, destin
  * @returns the reasonable percent on top of gas fee
  */
 export const reasonablePercentOnTopOfGasFee = ({ desiredExcessCompensationBasisPoints, }) => {
-    return (desiredExcessCompensationBasisPoints * (oneEther / basisPoints));
+    return desiredExcessCompensationBasisPoints * (oneEther / basisPoints);
 };
 /**
  * Calculates the desired compensation ratio from the desired excess compensation basis points
@@ -436,8 +449,279 @@ export const isUndercompensated = ({ estimatedTokenNetworkCost, feeType, limit,
     // 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;
+    }
+    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;
+};
+/**
+ * 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;
+    }
+    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;
+};
+/**
+ * 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.`;
+    }
+    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;
+};
+/**
+ * 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 (see `pulseXConversionSwapPath`),
+ *   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;
+    }
+    if (!routerAddress) {
+        return null;
+    }
+    if (!recipient || !isAddress(recipient) || recipient === zeroAddress) {
+        return null;
+    }
+    if (swapPath.length < 2) {
+        return null;
+    }
+    if (amountIn <= 0n) {
+        return null;
+    }
+    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;
+    }
+    if (fromIsNative) {
+        return {
+            to: routerAddress,
+            value: amountIn,
+            data: encodeFunctionData({
+                abi: abis.univ2Router,
+                functionName: 'swapExactETHForTokens',
+                args: [minAmountOut, swapPath, recipient, deadline],
+            }),
+        };
+    }
+    if (toIsNative) {
+        return {
+            to: routerAddress,
+            value: 0n,
+            data: encodeFunctionData({
+                abi: abis.univ2Router,
+                functionName: 'swapExactTokensForETH',
+                args: [amountIn, minAmountOut, swapPath, recipient, deadline],
+            }),
+        };
+    }
+    return {
+        to: routerAddress,
+        value: 0n,
+        data: encodeFunctionData({
+            abi: abis.univ2Router,
+            functionName: 'swapExactTokensForTokens',
+            args: [amountIn, minAmountOut, swapPath, recipient, deadline],
+        }),
+    };
+};
 /**
  * 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
@@ -447,35 +731,32 @@ export const isUndercompensated = ({ estimatedTokenNetworkCost, feeType, limit,
  * @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
+ * @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 = ({ bridgePathway, assetIn, recipient, account, assetLink, destinationDataParam, amountToBridge, feeDirectorStructEncoded, shouldDeliver, }) => {
+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) {
-        console.log('no bridge pathway');
         return null;
     }
     // check that recipient is valid
-    if (!recipient ||
-        !isAddress(recipient) ||
-        account === zeroAddress) {
-        console.log('no recipient');
+    if (!recipient || !isAddress(recipient) || recipient === zeroAddress) {
         return null;
     }
     // check that wallet account is valid
-    if (!account ||
-        !isAddress(account) ||
-        account === zeroAddress) {
-        console.log('no account');
+    if (!account || !isAddress(account) || account === zeroAddress) {
         return null;
     }
     // check that asset in is valid
     if (!assetIn) {
-        console.log('no asset in');
         return null;
     }
     // check that asset link is valid
     if (!assetLink) {
-        console.log('no asset link');
         return null;
     }
     let value = 0n;
@@ -500,12 +781,7 @@ export const transactionInputs = ({ bridgePathway, assetIn, recipient, account,
             ? encodeFunctionData({
                 abi: abis.erc677ExtraInput,
                 functionName: 'transferAndCall',
-                args: [
-                    bridgePathway.from,
-                    amountToBridge,
-                    destinationDataParam,
-                    account,
-                ],
+                args: [bridgePathway.from, amountToBridge, destinationDataParam, account],
             })
             : encodeFunctionData({
                 abi: abis.erc677,
@@ -526,11 +802,7 @@ export const transactionInputs = ({ bridgePathway, assetIn, recipient, account,
                 ? encodeFunctionData({
                     abi: abis.nativeRouterExtraInput,
                     functionName: 'relayTokensAndCall',
-                    args: [
-                        bridgePathway.destinationRouter,
-                        feeDirectorStructEncoded,
-                        account,
-                    ],
+                    args: [bridgePathway.destinationRouter, feeDirectorStructEncoded, account],
                 })
                 : encodeFunctionData({
                     abi: abis.nativeRouter,
@@ -588,12 +860,7 @@ export const transactionInputs = ({ bridgePathway, assetIn, recipient, account,
                 ? encodeFunctionData({
                     abi: abis.inputBridgeExtraInput,
                     functionName: 'relayTokens',
-                    args: [
-                        assetIn.address,
-                        recipient,
-                        amountToBridge,
-                        account,
-                    ],
+                    args: [assetIn.address, recipient, amountToBridge, account],
                 })
                 : encodeFunctionData({
                     abi: abis.inputBridge,

package/dist/ton-execution.d.ts

@@ -0,0 +1,117 @@
+import type { TonDeposit } from './origin-deposit.js';
+/**
+ * Executing a deposit on The Open Network, as pure data.
+ *
+ * Relay describes a deposit as a list of internal messages carrying `to`,
+ * `value`, `body` and a `bounce` flag. A connected wallet, however, is driven
+ * through the TON Connect protocol, whose request shape is different in one way
+ * that silently loses money:
+ *
+ * **TON Connect has no per-message `bounce` field.** A wallet derives whether a
+ * message bounces from the FORM OF THE ADDRESS — the bounceable `EQ…` prefix or
+ * the non-bounceable `UQ…` one. Passing Relay's address through unchanged while
+ * dropping its `bounce: false` therefore sends a deposit to the bounceable form,
+ * and the depository bounces the funds straight back to the sender. The transfer
+ * looks like it succeeded and the route never fills.
+ *
+ * {@link buildTonConnectRequest} folds `bounce` into the address so the flag
+ * cannot be dropped on the way to a wallet.
+ *
+ * Kept free of transport and of clock reads so it is fully testable: nothing
+ * here signs, fetches, or calls `Date.now`. The caller supplies the deadline and
+ * performs the request.
+ *
+ * The rules encoded here are those of Relay's own wallet adapter, which is the
+ * only reference implementation of this mapping.
+ */
+/**
+ * The TON Connect network identifier for mainnet. Relay bridges only mainnet, so
+ * a request is always tagged with this.
+ */
+export declare const tonConnectMainnetNetwork = "-239";
+/** How long a request stays valid by default, in seconds, matching Relay's adapter. */
+export declare const tonConnectDefaultValidForSeconds = 300;
+/** An address split into the parts that survive a change of encoding. */
+type ParsedTonAddress = {
+    workchain: number;
+    hash: Uint8Array;
+    /** Preserved rather than assumed: re-encoding a testnet address as mainnet would misdirect it. */
+    testOnly: boolean;
+};
+/**
+ * Parses either address form The Open Network uses.
+ *
+ * @param value - a friendly (`EQ…`/`UQ…`) or raw (`0:…`) address
+ * @returns the address parts, or null when it is neither form or fails its checksum
+ */
+export declare const parseTonAddress: (value: string) => ParsedTonAddress | null;
+/**
+ * Re-encodes an address into the friendly form matching a bounce setting.
+ *
+ * This is the whole point of the module: the bounce flag has nowhere else to
+ * live in a TON Connect request, so it has to be carried by the address itself.
+ *
+ * @param address - the address in either form
+ * @param options.bounceable - whether the message may bounce back to the sender
+ * @returns the friendly address, or null when the input cannot be parsed
+ */
+export declare const encodeTonAddress: (address: string, { bounceable }: {
+    bounceable: boolean;
+}) => string | null;
+/** One message of a TON Connect request. Note `address`/`amount`, not `to`/`value`. */
+export type TonConnectMessage = {
+    address: string;
+    /** Attached amount in nanotons, as a decimal string. */
+    amount: string;
+    /** Base64 bag-of-cells body, omitted when the message carries none. */
+    payload?: string;
+};
+/** The request handed to a wallet's TON Connect `sendTransaction` call. */
+export type TonConnectRequest = {
+    /** Unix seconds after which a wallet must refuse the request. */
+    validUntil: number;
+    network: string;
+    /** The sending account, when the deposit names one. */
+    from?: string;
+    messages: TonConnectMessage[];
+};
+/**
+ * Builds the TON Connect request for a deposit.
+ *
+ * @param deposit - the parsed origin deposit
+ * @param options.validUntil - unix seconds after which the request expires.
+ *   Supplied by the caller rather than read from a clock here so the transform
+ *   stays pure; {@link tonConnectDefaultValidForSeconds} is the usual offset.
+ * @returns the request, or null when the deposit carries no messages or any
+ *   destination address cannot be re-encoded — never a request whose bounce
+ *   setting has been silently dropped
+ */
+export declare const buildTonConnectRequest: (deposit: TonDeposit, { validUntil }: {
+    validUntil: number;
+}) => TonConnectRequest | null;
+/**
+ * Derives the transaction identifier from a wallet's `sendTransaction` response.
+ *
+ * A wallet answers with a `boc`: the base64 bag-of-cells of the signed
+ * external-in message it broadcast — NOT the resulting transaction, and NOT a
+ * hash. The identifier explorers and indexers (toncenter, TonAPI) resolve a
+ * transaction by is the hash of that external message, but it must be the
+ * NORMALIZED hash of TEP-467, not the hash of the bytes the wallet happened to
+ * send.
+ *
+ * The distinction is the whole point, and getting it wrong loses a resume record
+ * for real funds. An external-in message can be serialized several equivalent
+ * ways — a wallet may or may not include its own `src`, may set a non-zero
+ * `import_fee`, may attach a `stateInit`, may store the body inline or as a
+ * reference. The raw cell hash changes with each of those wallet-specific
+ * choices, so it frequently does NOT match what an indexer keyed the same
+ * transaction under. TEP-467 rebuilds the message with those variable fields
+ * stripped (`src` to none, `import_fee` to zero, `init` dropped, body forced to a
+ * reference) so the hash is stable across wallets and matches the indexers.
+ *
+ * @param boc - the wallet's base64 `boc` field from `sendTransaction`
+ * @returns the 64-character hex normalized hash, or null when the input is not a
+ *   parseable external-in message
+ */
+export declare const tonExternalMessageHash: (boc: string) => string | null;
+export {};