@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/settings.d.ts

@@ -0,0 +1,692 @@
+import { type Hex } from 'viem';
+import type { TokenBridgeInfo } from './chain-info.js';
+import { type Chains, type Pathway } from './config.js';
+import { FeeType } from './fee-type.js';
+import type { BridgeKey, Token } from './types.js';
+export declare const oneEther: bigint;
+export declare 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 declare const bridgePathway: ({ bridgeKey, isProd, assetIn, }: {
+    bridgeKey: BridgeKey;
+    isProd: boolean;
+    assetIn: Token | null;
+}) => Pathway | 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 declare const amountToBridge: ({ amountIn, assetIn, }: {
+    amountIn: bigint | null;
+    assetIn: Token | null;
+}) => bigint;
+/**
+ * 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 declare const bridgeCost: ({ amountToBridge, bridgeFee, }: {
+    amountToBridge: bigint;
+    bridgeFee: bigint | null;
+}) => bigint | null;
+/**
+ * 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 declare const amountAfterBridgeFee: ({ amountToBridge, bridgeCost, }: {
+    amountToBridge: bigint;
+    bridgeCost: bigint | null;
+}) => bigint | null;
+/**
+ * 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 declare const estimatedAmountOut: ({ amountAfterBridgeFee, fee, }: {
+    amountAfterBridgeFee: bigint | null;
+    fee: bigint | null;
+}) => bigint | null;
+/**
+ * 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 declare const estimatedFee: ({ amountAfterBridgeFee, fee, percentFee, feeType, limit, costsToDeliver, }: {
+    amountAfterBridgeFee: bigint | null;
+    fee: bigint;
+    percentFee: bigint;
+    feeType: FeeType;
+    limit: bigint | null;
+    costsToDeliver: boolean;
+}) => bigint | 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 declare const estimatedNativeNetworkCost: ({ estimatedGas, latestBaseFeePerGas, requiresDelivery, }: {
+    estimatedGas: bigint | null;
+    latestBaseFeePerGas: bigint | null;
+    requiresDelivery: boolean;
+}) => bigint | null;
+/**
+ * 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 declare const estimatedTokenNetworkCost: ({ estimatedNativeNetworkCost, priceCorrective, decimals, oneTokenInt, }: {
+    estimatedNativeNetworkCost: bigint | null;
+    priceCorrective: bigint | null;
+    decimals: number | null;
+    oneTokenInt: bigint | null;
+}) => bigint | null;
+/**
+ * Calculates one token of the asset in as an int
+ * @param assetIn - the asset in to bridge
+ * @returns the one token int
+ */
+export declare const oneTokenInt: ({ assetIn }: {
+    assetIn: Token | null;
+}) => bigint;
+/**
+ * Returns the limit as a bigint. Nil uses 0n
+ * @param lim - the limit
+ * @returns the limit
+ */
+export declare const limit: (lim: bigint | null) => bigint;
+/**
+ * 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 declare const networkSwitchAssetOutAddress: ({ assetOut, unwrap, toChain, }: {
+    assetOut: Token | null;
+    unwrap: boolean;
+    toChain: Chains;
+}) => string | null;
+/**
+ * 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 declare const desiredExcessCompensationBasisPoints: ({ path, assetIn, assetOut, bridgeKey, feeType, list, assetOutAddress, }: {
+    path: Pathway | null;
+    assetIn: Token | null;
+    assetOut: Token | null;
+    bridgeKey: BridgeKey;
+    feeType: FeeType;
+    list: Set<string>;
+    assetOutAddress: string | null;
+}) => 0n | 10000n | 1000n | 5000n;
+/**
+ * What the Gibs delivery service takes from a transfer, stated so a reader can
+ * tell "no delivery" from "delivery not yet priced".
+ *
+ * WHY A UNION AND NOT A NULLABLE AMOUNT. The function this replaced returned null
+ * both when the reader switched delivery off and when the fee was not known yet. Those
+ * two mean opposite things for a route's cost: the first is a real zero, the
+ * second makes any total a guess. A cost built from the null could only pick one
+ * reading, and whichever it picked was wrong half the time.
+ *
+ * - `not-requested` — nothing is delivered for a fee, so the fee is zero.
+ * - `requested` — delivery is on. `amount` is null until it is known.
+ *
+ * The amount is in base units of the token the destination router receives:
+ * the delivery router takes its fee from the value that arrives on the
+ * destination chain, after the bridge's own fee.
+ */
+export type DeliveryFee = {
+    status: 'not-requested';
+} | {
+    status: 'requested';
+    /** The fee in base units of the delivered token, or null while unknown. */
+    amount: bigint | null;
+    /**
+     * The share of the arriving value the fee takes, as a fraction of one
+     * ether (5e14 is 0.05%). Null when the fee is not a share of the value
+     * (fixed and gas modes) or the share is not known yet.
+     */
+    rate: bigint | null;
+};
+/**
+ * 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 declare const deliveryFee: ({ shouldDeliver, routeOffersDelivery, feeType, amountAfterBridgeFee, percentFee, fixedFee, limit, }: {
+    shouldDeliver: boolean;
+    routeOffersDelivery: boolean;
+    feeType: FeeType;
+    amountAfterBridgeFee: bigint | null;
+    percentFee: bigint | null;
+    fixedFee: bigint | null;
+    limit: bigint | null;
+}) => DeliveryFee;
+/**
+ * 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 declare const reasonableFixedFee: ({ estimatedTokenNetworkCost, desiredExcessCompensationBasisPoints, }: {
+    estimatedTokenNetworkCost: bigint | null;
+    desiredExcessCompensationBasisPoints: bigint;
+}) => bigint | null;
+/**
+ * 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 declare const reasonablePercentOnGasLimit: ({ gasTipFee, estimatedTokenNetworkCost, }: {
+    gasTipFee: bigint | null;
+    estimatedTokenNetworkCost: bigint | null;
+}) => bigint;
+/**
+ * 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 declare const reasonablePercentFee: ({ reasonableFixedFee, amountAfterBridgeFee, }: {
+    reasonableFixedFee: bigint | null;
+    amountAfterBridgeFee: bigint | null;
+}) => bigint | null;
+/**
+ * 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 declare const interactingWithBridgeToken: ({ assetLink, assetInAddress, }: {
+    assetLink: TokenBridgeInfo | null;
+    assetInAddress: string | null;
+}) => boolean;
+/**
+ * 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 declare const feeDirectorStructEncoded: ({ recipient, bridgePathway, feeType, priceCorrective, gasTipFee, percentFee, feeTypeSettings, limit, assetOut, }: {
+    recipient: Hex | null;
+    feeType: FeeType;
+    priceCorrective: bigint | null;
+    gasTipFee: bigint | null;
+    percentFee: bigint | null;
+    feeTypeSettings: bigint;
+    limit: bigint;
+    bridgePathway: Pathway | null;
+    assetOut: Token | null;
+}) => `0x${string}` | null;
+/**
+ * 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 declare const destinationDataParam: ({ recipient, bridgePathway, assetIn, destinationRouter, feeDirectorStructEncoded, assetLink, shouldDeliver, unwrap, }: {
+    recipient: Hex | null;
+    bridgePathway: Pathway | null;
+    assetIn: Token | null;
+    destinationRouter: Hex | null;
+    feeDirectorStructEncoded: Hex | null;
+    assetLink: TokenBridgeInfo | null;
+    shouldDeliver: boolean;
+    unwrap: boolean;
+}) => `0x${string}` | null;
+/**
+ * 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 declare const reasonablePercentOnTopOfGasFee: ({ desiredExcessCompensationBasisPoints, }: {
+    desiredExcessCompensationBasisPoints: bigint;
+}) => bigint;
+/**
+ * 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 declare const desiredCompensationRatio: ({ desiredExcessCompensationBasisPoints, }: {
+    desiredExcessCompensationBasisPoints: bigint;
+}) => bigint;
+/**
+ * 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 declare const availableCompensationMaximum: ({ amountAfterBridgeFee, percentFee, feeType, fixedFee, limit, }: {
+    amountAfterBridgeFee: bigint | null;
+    percentFee: bigint | null;
+    feeType: FeeType;
+    fixedFee: bigint | null;
+    limit: bigint;
+}) => bigint | null;
+/**
+ * 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 declare const isUndercompensated: ({ estimatedTokenNetworkCost, feeType, limit, amountAfterBridgeFee, desiredExcessCompensationBasisPoints, }: {
+    estimatedTokenNetworkCost: bigint | null;
+    feeType: FeeType;
+    limit: bigint;
+    amountAfterBridgeFee: bigint | null;
+    desiredExcessCompensationBasisPoints: bigint;
+}) => boolean;
+/**
+ * The chain pair a surface is showing the reader, in decimal chain ids.
+ *
+ * This is what the reader BELIEVES they are doing — the pair in the address bar
+ * and on the destination pill — as distinct from the pair the bridge key
+ * resolves a pathway for. The two are separate values that nothing forced to
+ * agree, which is the whole reason this type exists.
+ */
+export type SignedCrossing = {
+    /** The chain the reader's funds start on, as the surface states it. */
+    originChainId: number;
+    /** The chain the reader asked to receive on, as the surface states it. */
+    destinationChainId: number;
+};
+/**
+ * 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 declare const crossingRefusal: ({ bridgeKey, signedCrossing, }: {
+    bridgeKey: BridgeKey | null;
+    signedCrossing: SignedCrossing | null;
+}) => string | 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 declare const assertCrossingAgrees: ({ bridgeKey, signedCrossing, }: {
+    bridgeKey: BridgeKey | null;
+    signedCrossing: SignedCrossing | null;
+}) => void;
+/**
+ * The one chain a surface is showing the reader for a SAME-CHAIN swap — the
+ * PulseX leg's own equivalent of {@link SignedCrossing}.
+ *
+ * KEPT AS ITS OWN TYPE RATHER THAN A `SignedCrossing` WITH BOTH FIELDS EQUAL.
+ * That shape still reads as a crossing that goes nowhere, and
+ * {@link crossingRefusal} already treats origin-equals-destination as exactly
+ * that: a crossing to refuse, because no omnibridge pathway serves it. A swap
+ * needs to say the OPPOSITE thing about the very same fact — "this signature
+ * never leaves the chain, on purpose, and that is not an error" — so it needs
+ * a name a caller cannot confuse with a crossing.
+ */
+export type SignedSwap = {
+    /** The one chain both the swap's input and output live on. */
+    chainId: number;
+};
+/**
+ * What a surface believes ONE signature performs: a CROSSING between two
+ * chains, or a SWAP that stays on one.
+ *
+ * THE DISCRIMINANT IS EXPLICIT, never inferred from
+ * `originChainId === destinationChainId`. Inferring it would let a same-chain
+ * CROSSING selection — the exact case {@link crossingRefusal} already refuses,
+ * because no omnibridge pathway serves it — satisfy a caller building a swap
+ * transaction, which is a different signature entirely.
+ *
+ * EXTENDS THE CROSSING GUARD RATHER THAN REPLACING IT. {@link SignedCrossing},
+ * {@link crossingRefusal}, {@link assertCrossingAgrees} and
+ * {@link transactionInputs} are all UNCHANGED by this type's existence: every
+ * crossing still refuses exactly as it did before a swap leg existed at all.
+ *
+ * FOUR KINDS, ONE PER SENDER. A two-chain move is signed three different
+ * ways, and each way is its own kind so a signature built for one can never
+ * satisfy a sender built for another:
+ *
+ * - `'crossing'` — the omnibridge's own entry or exit call, signed by the
+ *   reader's wallet against the bridge contracts.
+ * - `'aggregator'` — a provider's quote (Relay, LI.FI, NEAR Intents) that the
+ *   reader's wallet signs; the provider carries the funds, and may perform
+ *   the omnibridge entry call itself on arrival.
+ * - `'deposit-address'` — nothing is signed at all: the provider reserves an
+ *   address and the reader pays it by hand from any wallet.
+ * - `'swap'` — a same-chain PulseX trade or native wrap.
+ *
+ * The three two-chain kinds share {@link SignedCrossing}'s fields, because
+ * each one still moves funds from one chain to another.
+ */
+export type SignedLeg = ({
+    kind: 'crossing';
+} & SignedCrossing) | ({
+    kind: 'aggregator';
+} & SignedCrossing) | ({
+    kind: 'deposit-address';
+} & SignedCrossing) | ({
+    kind: 'swap';
+} & SignedSwap);
+/**
+ * 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 declare const swapRefusal: ({ signedLeg, chainId, }: {
+    signedLeg: SignedLeg | null;
+    chainId: number | null;
+}) => string | 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 declare const assertSwapAgrees: ({ signedLeg, chainId, }: {
+    signedLeg: SignedLeg | null;
+    chainId: number | null;
+}) => void;
+/**
+ * Which priced {@link import('./routing/candidate.js').RouteCandidate} a
+ * route was built to sign, which of the route's `sections` that candidate's
+ * quote answers for, and what KIND of leg that section is.
+ *
+ * WHY A BARE CANDIDATE IDENTIFIER IS NOT ENOUGH. A route's `candidateId` names
+ * the priced candidate an execute button broadcasts, but names nothing about
+ * WHICH of the route's sections that candidate's quote is for, or whether the
+ * section is a two-chain CROSSING or a same-chain SWAP. A composed route can
+ * carry more than one section — bridge an anchor token onto PulseChain, then a
+ * DEFERRED PulseX swap to the token the reader actually wants — and each
+ * section's calldata is built by a DIFFERENT sender component, chosen by the
+ * route's `kind`, entirely independently of the candidate id. Nothing today
+ * stops a future producer from stamping a candidate id onto a route while
+ * leaving its leg unstated, or a future sender from reaching for a candidate
+ * built for one leg to sign a different one — the same shape of mistake
+ * {@link SignedCrossing}/{@link SignedLeg} already exist to catch for what is
+ * on screen, one layer up from here.
+ *
+ * `leg` reuses {@link SignedLeg}'s own discriminant deliberately: a signature
+ * is either a crossing or a swap everywhere else in this codebase, and a
+ * candidate's pick has no reason to invent a second vocabulary for the same
+ * fact.
+ */
+export type CandidatePick = {
+    /** The {@link import('./routing/candidate.js').RouteCandidate.id} this pick names. */
+    readonly candidateId: string;
+    /** The route's `sections` index this candidate's quote signs. */
+    readonly sectionIndex: number;
+    /** Whether the signed section is a two-chain crossing or a same-chain swap. */
+    readonly leg: SignedLeg['kind'];
+};
+/**
+ * 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 declare const candidatePickRefusal: ({ pick, leg, sectionIndex, }: {
+    pick: CandidatePick | null;
+    leg: SignedLeg["kind"];
+    sectionIndex: number;
+}) => string | 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 declare const assertCandidatePickAgrees: ({ pick, leg, sectionIndex, }: {
+    pick: CandidatePick | null;
+    leg: SignedLeg["kind"];
+    sectionIndex: number;
+}) => void;
+/**
+ * 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 declare const pulseXSwapTransactionInputs: ({ signedLeg, chainId, routerAddress, fromTokenAddress, toTokenAddress, swapPath, amountIn, minAmountOut, recipient, deadline, }: {
+    signedLeg: SignedLeg | null;
+    chainId: number | null;
+    routerAddress: Hex | null;
+    fromTokenAddress: Hex;
+    toTokenAddress: Hex;
+    swapPath: readonly Hex[];
+    amountIn: bigint;
+    minAmountOut: bigint;
+    recipient: Hex | null;
+    deadline: bigint;
+}) => {
+    to: `0x${string}`;
+    value: bigint;
+    data: `0x${string}`;
+} | null;
+/**
+ * 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 declare const transactionInputs: ({ bridgeKey, signedCrossing, bridgePathway, assetIn, recipient, account, assetLink, destinationDataParam, amountToBridge, feeDirectorStructEncoded, shouldDeliver, }: {
+    bridgeKey: BridgeKey | null;
+    signedCrossing: SignedCrossing | null;
+    bridgePathway: Pathway | null;
+    assetIn: Token | null;
+    recipient: Hex | null;
+    account: Hex | null;
+    assetLink: TokenBridgeInfo | null;
+    destinationDataParam: Hex | null;
+    amountToBridge: bigint;
+    feeDirectorStructEncoded: Hex | null;
+    shouldDeliver: boolean;
+}) => {
+    to: `0x${string}`;
+    value: bigint;
+    data: `0x${string}`;
+} | null;
+/**
+ * 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 declare const assetOutKey: ({ bridgeKeyPath, assetInAddress, unwrap, }: {
+    bridgeKeyPath: string;
+    assetInAddress?: Hex | null;
+    unwrap: boolean;
+}) => string | null;
+/**
+ * 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 declare const assetOut: ({ assetInAddress, assetsOut, bridgeKeyPath, unwrap, }: {
+    assetInAddress: Hex | null;
+    assetsOut: Map<string, Token>;
+    bridgeKeyPath: string;
+    unwrap: boolean;
+}) => Token | null;