@gibs/bridge-sdk 1.13.1 → 1.18.0

package/dist/routing/swap-transactions.d.ts

@@ -0,0 +1,95 @@
+import { type Hex } from 'viem';
+import { type SignedLeg } from '../settings.js';
+import type { SwapVenues } from '../swap-venues.js';
+import type { HopEdge, PlannedHop } from './search/graph.js';
+/**
+ * The same-chain, one-signature transaction shape every sender in this file
+ * builds: a target contract, a native-coin value, and encoded calldata.
+ */
+export type SwapCallInputs = {
+    readonly to: Hex;
+    readonly value: bigint;
+    readonly data: Hex;
+};
+/**
+ * Builds a same-chain PulseX swap transaction for one planned route-search
+ * hop. The interface's section signing (`packages/ui` `state/sectionSigning.ts`)
+ * and the SDK's execution planner (`execution.ts`) both call it, so there is
+ * exactly one place that turns "swap this hop" into calldata.
+ *
+ * SIGNS THE PATH THE HOP WAS PRICED ON. The PulseX carrier picks the best of
+ * many paths through its hub tokens and records the winner on the hop's
+ * outcome; `pulseXSwapPathForHop` (`carriers/pulsex.ts`) reads it back
+ * and checks it fits the hop's edge. This never rebuilds a path: a rebuilt
+ * path is a quote on one route and a signature on another. A hop that
+ * records no path is refused. REUSES `pulseXSwapTransactionInputs` (`settings.ts`)
+ * for the encoding, never re-implements it: that function already carries the
+ * `swapRefusal` guard (refuses to build a call for a leg the screen is not
+ * looking at) and the native-in/native-out/token-token branching.
+ *
+ * SIGNS ON THE EDGE'S OWN ROUTER. A PulseX edge names the deployment it was
+ * quoted on (`venueForEdge`: V1 or V2, each with its own pools). The
+ * caller's `routerAddress` must be that same router — it is also the router
+ * the caller approved to spend the input token — or nothing is built. A V2
+ * quote signed on V1 would trade against a different pool than the one the
+ * reader was shown.
+ *
+ * @param options - the hop to swap, the amount and slippage-adjusted
+ *   minimum, who receives the output, the signing deadline, what the caller
+ *   believes this signature does (`signedLeg`), the chain it executes on, the
+ *   resolved router address, and the swap venues the router must belong to
+ *   (the defaults when omitted)
+ * @returns the swap transaction inputs, or null when the hop records no
+ *   PulseX swap path, names no known router, `routerAddress` is not the
+ *   edge's own router, the leg on screen disagrees, or any of
+ *   `pulseXSwapTransactionInputs`'s own preconditions are unmet
+ */
+export declare const buildPulseXSwapTransaction: (options: {
+    readonly hop: Pick<PlannedHop, "edge" | "outcome">;
+    readonly amountIn: bigint;
+    readonly minAmountOut: bigint;
+    readonly recipient: Hex | null;
+    readonly deadline: bigint;
+    readonly signedLeg: SignedLeg | null;
+    readonly chainId: number | null;
+    readonly routerAddress: Hex | null;
+    /** The venues the edge's router must belong to. Omitted means the defaults. */
+    readonly venues?: SwapVenues;
+}) => SwapCallInputs | null;
+/**
+ * Builds a native-coin wrap/unwrap transaction for one route-search graph
+ * edge — PLS<->WPLS on PulseChain, ETH<->WETH on Ethereum, or the same pair
+ * on any other chain `config.ts`'s `nativeAssetOut` names one for.
+ *
+ * A WRAP IS NOT A SWAP CALL. There is no PulseX pool for native-versus-wrapped
+ * — see `routing/carriers/wrap.ts`'s own doc — so this never touches the
+ * PulseX router: wrapping sends `amountIn` native coin to the wrapped token's
+ * own `deposit()`; unwrapping calls `withdraw(amountIn)` on it with zero
+ * value. The `edge` names which direction: its `from`/`to` addresses are
+ * checked against the zero-address sentinel, never assumed from a caller
+ * flag, so a swapped/malformed edge is refused rather than guessed at.
+ *
+ * @param options - the edge to wrap or unwrap, and the amount in the SOURCE
+ *   token's base units (native units wrapping, wrapped units unwrapping —
+ *   native and wrapped share decimals on every chain this carrier covers)
+ * @returns the wrap/unwrap transaction inputs, or null when `amountIn` is not
+ *   positive or the edge is not exactly one native/wrapped pair
+ */
+export declare const buildWrapTransaction: (options: {
+    readonly edge: HopEdge;
+    readonly amountIn: bigint;
+}) => SwapCallInputs | null;
+/**
+ * The slippage floor a swap signs: the quoted output less the slippage
+ * allowance, rounded down. The interface's engine signing and the SDK's
+ * execution planner both read it, so the two never sign different floors for
+ * the same quote.
+ *
+ * @param options.quotedAmount - the hop's quoted output, in the output token's base units
+ * @param options.slippageBasisPoints - the allowance, in basis points (100 is 1%)
+ * @returns the minimum output the swap accepts
+ */
+export declare const swapMinimumOut: ({ quotedAmount, slippageBasisPoints, }: {
+    readonly quotedAmount: bigint;
+    readonly slippageBasisPoints: bigint;
+}) => bigint;

package/dist/routing/swap-transactions.js

@@ -0,0 +1,127 @@
+import { encodeFunctionData, isAddressEqual, parseAbi, zeroAddress } from 'viem';
+import { pulseXSwapTransactionInputs } from '../settings.js';
+import { defaultSwapVenues } from '../config.js';
+import { pulseXSwapPathForHop, venueForEdge } from './carriers/pulsex.js';
+/**
+ * The minimal WETH9-style wrap/unwrap interface: `deposit()` mints the
+ * wrapped token for the native coin sent with the call, `withdraw(uint256)`
+ * burns wrapped balance and returns native coin. Every wrapped-native
+ * contract this application bridges to exposes exactly this pair — see
+ * `carriers/wrap.ts`, whose own doc records the selectors as confirmed
+ * present on WPLS by bytecode inspection (2026-09-24). Kept local rather than
+ * added to `@gibs/abis`: the interface is two standard, unchanging selectors
+ * rather than a contract-specific ABI.
+ */
+const wrapAbi = parseAbi(['function deposit() payable', 'function withdraw(uint256 amount)']);
+/**
+ * Builds a same-chain PulseX swap transaction for one planned route-search
+ * hop. The interface's section signing (`packages/ui` `state/sectionSigning.ts`)
+ * and the SDK's execution planner (`execution.ts`) both call it, so there is
+ * exactly one place that turns "swap this hop" into calldata.
+ *
+ * SIGNS THE PATH THE HOP WAS PRICED ON. The PulseX carrier picks the best of
+ * many paths through its hub tokens and records the winner on the hop's
+ * outcome; `pulseXSwapPathForHop` (`carriers/pulsex.ts`) reads it back
+ * and checks it fits the hop's edge. This never rebuilds a path: a rebuilt
+ * path is a quote on one route and a signature on another. A hop that
+ * records no path is refused. REUSES `pulseXSwapTransactionInputs` (`settings.ts`)
+ * for the encoding, never re-implements it: that function already carries the
+ * `swapRefusal` guard (refuses to build a call for a leg the screen is not
+ * looking at) and the native-in/native-out/token-token branching.
+ *
+ * SIGNS ON THE EDGE'S OWN ROUTER. A PulseX edge names the deployment it was
+ * quoted on (`venueForEdge`: V1 or V2, each with its own pools). The
+ * caller's `routerAddress` must be that same router — it is also the router
+ * the caller approved to spend the input token — or nothing is built. A V2
+ * quote signed on V1 would trade against a different pool than the one the
+ * reader was shown.
+ *
+ * @param options - the hop to swap, the amount and slippage-adjusted
+ *   minimum, who receives the output, the signing deadline, what the caller
+ *   believes this signature does (`signedLeg`), the chain it executes on, the
+ *   resolved router address, and the swap venues the router must belong to
+ *   (the defaults when omitted)
+ * @returns the swap transaction inputs, or null when the hop records no
+ *   PulseX swap path, names no known router, `routerAddress` is not the
+ *   edge's own router, the leg on screen disagrees, or any of
+ *   `pulseXSwapTransactionInputs`'s own preconditions are unmet
+ */
+export const buildPulseXSwapTransaction = (options) => {
+    const { hop, amountIn, minAmountOut, recipient, deadline, signedLeg, chainId, routerAddress } = options;
+    const { edge } = hop;
+    const swapPath = pulseXSwapPathForHop(hop);
+    if (swapPath === null) {
+        return null;
+    }
+    const quotedRouter = venueForEdge(options.venues ?? defaultSwapVenues, edge)?.router ?? null;
+    if (quotedRouter === null || routerAddress === null || !isAddressEqual(quotedRouter, routerAddress)) {
+        return null;
+    }
+    return pulseXSwapTransactionInputs({
+        signedLeg,
+        chainId,
+        routerAddress,
+        fromTokenAddress: edge.from.address,
+        toTokenAddress: edge.to.address,
+        swapPath,
+        amountIn,
+        minAmountOut,
+        recipient,
+        deadline,
+    });
+};
+/**
+ * Builds a native-coin wrap/unwrap transaction for one route-search graph
+ * edge — PLS<->WPLS on PulseChain, ETH<->WETH on Ethereum, or the same pair
+ * on any other chain `config.ts`'s `nativeAssetOut` names one for.
+ *
+ * A WRAP IS NOT A SWAP CALL. There is no PulseX pool for native-versus-wrapped
+ * — see `routing/carriers/wrap.ts`'s own doc — so this never touches the
+ * PulseX router: wrapping sends `amountIn` native coin to the wrapped token's
+ * own `deposit()`; unwrapping calls `withdraw(amountIn)` on it with zero
+ * value. The `edge` names which direction: its `from`/`to` addresses are
+ * checked against the zero-address sentinel, never assumed from a caller
+ * flag, so a swapped/malformed edge is refused rather than guessed at.
+ *
+ * @param options - the edge to wrap or unwrap, and the amount in the SOURCE
+ *   token's base units (native units wrapping, wrapped units unwrapping —
+ *   native and wrapped share decimals on every chain this carrier covers)
+ * @returns the wrap/unwrap transaction inputs, or null when `amountIn` is not
+ *   positive or the edge is not exactly one native/wrapped pair
+ */
+export const buildWrapTransaction = (options) => {
+    const { edge, amountIn } = options;
+    if (amountIn <= 0n) {
+        return null;
+    }
+    const fromIsNative = edge.from.address.toLowerCase() === zeroAddress;
+    const toIsNative = edge.to.address.toLowerCase() === zeroAddress;
+    // Exactly one side must be the native sentinel — a token/token pair, or a
+    // native/native no-op, is not a wrap edge at all.
+    if (fromIsNative === toIsNative) {
+        return null;
+    }
+    if (fromIsNative) {
+        return {
+            to: edge.to.address,
+            value: amountIn,
+            data: encodeFunctionData({ abi: wrapAbi, functionName: 'deposit', args: [] }),
+        };
+    }
+    return {
+        to: edge.from.address,
+        value: 0n,
+        data: encodeFunctionData({ abi: wrapAbi, functionName: 'withdraw', args: [amountIn] }),
+    };
+};
+/**
+ * The slippage floor a swap signs: the quoted output less the slippage
+ * allowance, rounded down. The interface's engine signing and the SDK's
+ * execution planner both read it, so the two never sign different floors for
+ * the same quote.
+ *
+ * @param options.quotedAmount - the hop's quoted output, in the output token's base units
+ * @param options.slippageBasisPoints - the allowance, in basis points (100 is 1%)
+ * @returns the minimum output the swap accepts
+ */
+export const swapMinimumOut = ({ quotedAmount, slippageBasisPoints, }) => (quotedAmount * (10000n - slippageBasisPoints)) / 10000n;

package/dist/settings.d.ts

@@ -212,6 +212,98 @@ export declare const deliveryFee: ({ shouldDeliver, routeOffersDelivery, feeType
     fixedFee: bigint | null;
     limit: bigint | null;
 }) => 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}
+ */
+export declare const feeTypeSettings: ({ feeType, unwrap }: {
+    feeType: FeeType;
+    unwrap: boolean;
+}) => bigint;
+/**
+ * An ERC-20 allowance a transaction needs before it can run: `spender` must
+ * be allowed to pull at least `minimum` of `token` from the sender on
+ * `chainId`.
+ */
+export type ApprovalRequirement = {
+    chainId: number;
+    token: Hex;
+    spender: Hex;
+    minimum: bigint;
+};
+/**
+ * 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 declare const approveCall: ({ token, spender, amount, }: {
+    token: Hex;
+    spender: Hex;
+    amount: bigint;
+}) => {
+    to: Hex;
+    value: bigint;
+    data: Hex;
+};
+/**
+ * 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 declare const approvalAmounts: ({ allowance, minimum, }: {
+    allowance: bigint;
+    minimum: bigint;
+}) => readonly bigint[];
+/**
+ * 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 declare const omnibridgeApproval: ({ bridgePathway, assetIn, assetLink, amountToBridge, }: {
+    bridgePathway: Pathway;
+    assetIn: Token;
+    assetLink: TokenBridgeInfo;
+    amountToBridge: bigint;
+}) => ApprovalRequirement | null;
 /**
  * Calculates the reasonable fixed fee from the estimated token network cost and desired excess compensation basis points
  * @param estimatedTokenNetworkCost - the estimated token network cost
@@ -605,7 +697,8 @@ export declare const assertCandidatePickAgrees: ({ pick, leg, sectionIndex, }: {
  *   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`),
+ * @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

package/dist/settings.js

@@ -1,4 +1,4 @@
-import { concatHex, encodeAbiParameters, encodeFunctionData, getAddress, isAddress, isAddressEqual, zeroAddress, } from 'viem';
+import { concatHex, encodeAbiParameters, encodeFunctionData, erc20Abi, 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';
@@ -230,6 +230,95 @@ 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;
+    const excludePriorityBit = 1n;
+    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 [];
+    if (allowance === 0n)
+        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;
+    if (interactingWithBridgeToken({ assetLink, assetInAddress: assetIn.address }))
+        return null;
+    return {
+        chainId: assetIn.chainId,
+        token: assetIn.address,
+        spender: bridgePathway.from,
+        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
@@ -358,7 +447,9 @@ export const destinationDataParam = ({ recipient, bridgePathway, assetIn, destin
     if (!destinationRouter) {
         return null;
     }
-    if (bridgePathway.requiresDelivery && !feeDirectorStructEncoded) {
+    // 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) {
@@ -653,7 +744,8 @@ export const assertCandidatePickAgrees = ({ pick, leg, sectionIndex, }) => {
  *   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`),
+ * @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

package/dist/swap-venues.d.ts

@@ -0,0 +1,43 @@
+import type { Hex } from 'viem';
+/**
+ * A place a same-chain token swap can execute. Today only Uniswap-V2-shaped
+ * routers exist: `getAmountsOut`, `swapExactTokensForTokens`,
+ * `swapExactETHForTokens`, `swapExactTokensForETH`, a factory with
+ * `getPair`, and pairs with `getReserves`. The `kind` field leaves room for
+ * other shapes (for example `'uniswap-v3'`) without breaking callers.
+ */
+export type SwapVenue = {
+    /** The router shape. Only `'uniswap-v2'` is supported. */
+    readonly kind: 'uniswap-v2';
+    /** The numeric chain id the router lives on. */
+    readonly chainId: number;
+    /** The router a swap is signed on. It is also the token approval spender. */
+    readonly router: Hex;
+    /** The factory whose pools the router trades against. */
+    readonly factory: Hex;
+    /** The swap fee in basis points: 29 for PulseX, 30 for Uniswap V2 forks. */
+    readonly feeBasisPoints: number;
+    /** A name for logs and displays. */
+    readonly label?: string;
+};
+/** The venues on each chain, keyed by numeric chain id. The first venue of a chain is its default. */
+export type SwapVenues = Readonly<Record<number, readonly SwapVenue[]>>;
+/**
+ * Merges caller venues over {@link defaultSwapVenues}. A chain present in
+ * `overrides` replaces the default list for that chain. A chain absent from
+ * `overrides` keeps its default list. An empty list switches swaps off on
+ * that chain. Neither input is changed; the result is frozen.
+ *
+ * @param overrides - the caller's venues, or undefined for the defaults
+ * @returns the venues to use
+ */
+export declare const resolveSwapVenues: (overrides?: SwapVenues) => SwapVenues;
+/**
+ * Finds the venue on a chain that has the given router.
+ *
+ * @param venues - the venues to search
+ * @param chainId - the numeric chain id
+ * @param router - the router address, in any letter case
+ * @returns the venue, or null when the chain has no venue with that router
+ */
+export declare const findSwapVenue: (venues: SwapVenues, chainId: number, router: Hex) => SwapVenue | null;

package/dist/swap-venues.js

@@ -0,0 +1,24 @@
+import { defaultSwapVenues } from './config.js';
+/**
+ * Merges caller venues over {@link defaultSwapVenues}. A chain present in
+ * `overrides` replaces the default list for that chain. A chain absent from
+ * `overrides` keeps its default list. An empty list switches swaps off on
+ * that chain. Neither input is changed; the result is frozen.
+ *
+ * @param overrides - the caller's venues, or undefined for the defaults
+ * @returns the venues to use
+ */
+export const resolveSwapVenues = (overrides) => {
+    if (overrides === undefined)
+        return defaultSwapVenues;
+    return Object.freeze({ ...defaultSwapVenues, ...overrides });
+};
+/**
+ * Finds the venue on a chain that has the given router.
+ *
+ * @param venues - the venues to search
+ * @param chainId - the numeric chain id
+ * @param router - the router address, in any letter case
+ * @returns the venue, or null when the chain has no venue with that router
+ */
+export const findSwapVenue = (venues, chainId, router) => venues[chainId]?.find((venue) => venue.router.toLowerCase() === router.toLowerCase()) ?? null;

package/dist/ton-connect.d.ts

@@ -0,0 +1,98 @@
+import type { TonDeposit } from './origin-deposit.js';
+/**
+ * Executing a deposit on The Open Network, as pure data, with no TON library.
+ *
+ * This module imports nothing outside the package, so it loads anywhere: a
+ * browser, Node, or a React Native app under Hermes, with no `Buffer` and no
+ * polyfill. It uses only `atob` and `btoa`, which Hermes provides. The one TON
+ * helper that needs `@ton/core`, the TEP-467 message hash, lives in
+ * `@gibs/bridge-sdk/ton` instead.
+ *
+ * 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;
+export {};