@gibs/bridge-sdk 1.19.0 → 1.20.0

package/dist/cjs/destination-calldata.js

@@ -3,77 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildDestinationCalldata = exports.destinationGasLimits = void 0;
 const viem_1 = require("viem");
 const settings_js_1 = require("./settings.js");
-/**
- * Conservative per-shape gas budgets for omnibridge entry calls executed by an
- * aggregator on the destination chain. An undershoot reverts the executor's
- * call and strands funds at the aggregator's fallback address, so these err
- * high; the aggregator prices unused gas into the quote rather than burning it.
- *
- * MEASURED against the deployed mediators on a fork of Ethereum mainnet,
- * 2026-08-31, by `destination-calldata.fork.test.ts`:
- *
- *   relayTokens         195,967   USD Coin, an ordinary registered token
- *   wrapAndRelayTokens  200,347   native ether through the router
- *   transferAndCall     187,000   wrapped Pulse, a bridged representation home
- *                                 to 204,000, depending on the fork block
- *
- * The figures move with block state — whether a storage slot the call touches
- * is already warm — so treat them as a band, not a constant. The spread
- * measured across two blocks minutes apart was about nine percent.
- *
- * THE BUDGET STAYS AT 400,000, and the headroom is deliberate. Every figure
- * above is a token the bridge has carried before. The first crossing of a
- * token the mediator has not seen writes its limits as well, and a token with
- * a transfer hook costs more again — neither is measured here, and both fail
- * by stranding the user's funds rather than by costing us a little gas. The
- * fork test asserts each shape stays under the budget, so a regression that
- * eats the headroom fails a test rather than a transfer.
- */
 exports.destinationGasLimits = {
     relayTokens: 400000n,
     transferAndCall: 400000n,
     wrapAndRelayTokens: 400000n,
 };
-/**
- * Builds the call an aggregator's executor must perform on the bridge's
- * foreign chain (e.g. Ethereum) to relay just-bridged funds onward through the
- * omnibridge to the recipient on the home chain (e.g. PulseChain).
- *
- * This is the second leg of a consolidated route: the aggregator bridges the
- * user's funds to the foreign chain with a guaranteed minimum amount, then its
- * executor performs this call. Because the executor — not the user — is the
- * caller, the result always encodes the fixed `amount` and names the user as
- * `recipient`; delivery-fee encoding never applies (home-chain gas handout is
- * a separate automatic system).
- *
- * @param pathway - the bridge pathway whose foreign side the executor enters
- * @param assetIn - the foreign-chain token the aggregator delivers (zero address for native)
- * @param recipient - the user's address on the home chain
- * @param sender - the user's address, threaded through pathways that take an extra sender param
- * @param assetLink - the asset link for the token, used to detect bridged representations
- * @param amount - the exact token amount the executor will relay
- * @returns the destination call, or null when the inputs cannot form a valid call
- */
 const buildDestinationCalldata = ({ pathway, assetIn, recipient, sender, assetLink, amount, unwrap = false, }) => {
     if (amount <= 0n) {
         return null;
     }
-    // `transactionInputs` rejects both of these too, but it cannot say so to the
-    // type checker, and the entry fields below are read straight off them. Asking
-    // first keeps the answer honest rather than asserted.
     if (!pathway || !assetLink) {
         return null;
     }
-    // THE UNWRAP RIDES THE DATA PARAMETER, which is the same slot the recipient
-    // travels in. Naming the destination router there and the recipient after it
-    // tells the home mediator to hand the arriving tokens to the router, which
-    // unwraps them and forwards the coin on. `destinationDataParam` owns that
-    // encoding for the direct path already, so it owns it here too rather than
-    // being restated.
-    //
-    // The gate is the pathway's own bridged native asset. Anything else arrives
-    // wrapped whatever the caller asked for, so obeying the request would build a
-    // call that does something other than what the caller believes it does.
     const unwrapOnArrival = unwrap &&
         assetIn !== null &&
         pathway.destinationRouter !== null &&
@@ -90,17 +31,10 @@ const buildDestinationCalldata = ({ pathway, assetIn, recipient, sender, assetLi
             unwrap: true,
         })
         : recipient;
-    // Only reachable when the unwrap was asked for and could not be encoded.
-    // Falling back to a plain recipient would quietly deliver the wrapped token.
     if (destinationData === null) {
         return null;
     }
     const inputs = (0, settings_js_1.transactionInputs)({
-        // NO READER COMPOSED THIS CALL, so there is no pair on screen for it to
-        // disagree with. An aggregator's executor performs it on the entry chain
-        // after the reader has already signed their own transaction, and the chain
-        // pair IS this pathway. See `crossingRefusal` for why the field is nullable
-        // rather than optional: every caller has to say which of the two it is.
         bridgeKey: null,
         signedCrossing: null,
         bridgePathway: pathway,
@@ -108,8 +42,6 @@ const buildDestinationCalldata = ({ pathway, assetIn, recipient, sender, assetLi
         recipient,
         account: sender,
         assetLink,
-        // for bridged tokens the data param rides transferAndCall and the
-        // mediator decodes it as the home-chain recipient
         destinationDataParam: destinationData,
         amountToBridge: amount,
         feeDirectorStructEncoded: null,
@@ -123,9 +55,6 @@ const buildDestinationCalldata = ({ pathway, assetIn, recipient, sender, assetLi
         assetLink,
         assetInAddress: assetIn?.address ?? null,
     });
-    // Both are the same for every shape: the pathway's own mediator, and the
-    // on-chain address the link resolved (already the wrapped one for a native
-    // asset, because `tokenBridgeInfo` substitutes it before looking anything up).
     const entry = {
         entryMediator: pathway.from,
         entryTokenAddress: assetLink.assetInAddress,

package/dist/cjs/ecosystems.js

@@ -2,47 +2,21 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeAddressIn = exports.isValidAddressIn = exports.isNativeAsset = exports.sameAddress = exports.ecosystemByCaipNamespace = exports.isEcosystemProvenEndToEnd = exports.ecosystemById = exports.ecosystemRegistry = void 0;
 const viem_1 = require("viem");
-// Solana public keys are base58 (no 0, O, I, l) and 32–44 characters long.
 const base58Solana = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
-// Bitcoin mainnet: bech32 (bc1…) or base58 pay-to-key/script (starts 1 or 3).
 const bech32Bitcoin = /^bc1[0-9ac-hj-np-z]{6,87}$/;
 const base58Bitcoin = /^[13][1-9A-HJ-NP-Za-km-z]{25,39}$/;
-// Tron base58check addresses are always 34 characters and always begin with a
-// capital T (the encoding of the 0x41 mainnet prefix byte).
 const base58Tron = /^T[1-9A-HJ-NP-Za-km-z]{33}$/;
-// The Open Network has two interchangeable address encodings, and Relay uses
-// both: the 48-character "user-friendly" base64url form (EQ/UQ on mainnet,
-// kQ/0Q on testnet), and the "raw" form of a workchain, a colon, and a
-// 64-character hex account identifier.
 const friendlyTon = /^[EUk0]Q[A-Za-z0-9_-]{46}$/;
 const rawTon = /^-?\d+:[0-9a-fA-F]{64}$/;
-// HyperCore token identifiers are hex of a length Ethereum never uses: sixteen
-// bytes for most tokens, nineteen for a few. Twenty is allowed too so a token
-// that is addressed by a full Ethereum address still resolves.
 const hyperliquidTokenId = /^0x[0-9a-fA-F]{32,40}$/;
-// Zcash TRANSPARENT addresses only, and the restriction is the service's, not
-// ours: a shielded (`zs1…`) or unified (`u1…`) address is refused at the door
-// with `refundTo is not valid`, before a solver is ever reached. Both
-// transparent forms are base58check over a two-byte prefix, which always
-// encodes to exactly 35 characters: `t1` pays to a public key hash, `t3` to a
-// script hash. The pattern rejects the shielded forms by construction, because
-// neither begins with `t`.
 const transparentZcash = /^t[13][1-9A-HJ-NP-Za-km-z]{33}$/;
 const evmDescriptor = {
     id: 'evm',
     label: 'Ethereum Virtual Machine',
     caipNamespace: 'eip155',
-    // The all-zero address, exactly as the Relay builder uses across every
-    // Ethereum Virtual Machine chain for the native gas token.
     nativeAssetSentinel: '0x0000000000000000000000000000000000000000',
-    // The only proof the product holds. The bridge's own contracts run on
-    // PulseChain, Ethereum and Binance Smart Chain, and every aggregator origin
-    // LI.FI carries is an Ethereum Virtual Machine chain, so this is the family
-    // real transfers have crossed.
     endToEndProof: 'verified',
     isValidAddress: (value) => (0, viem_1.isAddress)(value),
-    // getAddress applies the mixed-case checksum; it throws on a non-address, so
-    // fall back to the raw input to keep normalize total and side-effect-free.
     normalizeAddress: (value) => ((0, viem_1.isAddress)(value) ? (0, viem_1.getAddress)(value) : value),
     addressCasing: 'insensitive',
 };
@@ -50,16 +24,9 @@ const svmDescriptor = {
     id: 'svm',
     label: 'Solana',
     caipNamespace: 'solana',
-    // Solana native currency (the System Program address), as Relay expects it.
     nativeAssetSentinel: '11111111111111111111111111111111',
-    // Connects through the Reown AppKit Solana adapter and signs for real
-    // (`useSolanaDepositSigner` builds a versioned transaction and calls the
-    // wallet's sign-and-send). Every test around it drives a mocked wallet, and
-    // Relay — the only provider that quotes this origin — has never had its
-    // on-chain execution confirmed by a funded transfer.
     endToEndProof: 'pending',
     isValidAddress: (value) => base58Solana.test(value),
-    // base58 is case-significant; canonical form is the input unchanged.
     normalizeAddress: (value) => value,
     addressCasing: 'significant',
 };
@@ -67,17 +34,9 @@ const bvmDescriptor = {
     id: 'bvm',
     label: 'Bitcoin',
     caipNamespace: 'bip122',
-    // Bitcoin native currency string, as Relay expects it.
     nativeAssetSentinel: 'bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8',
-    // The best-evidenced of the four, and still short of proof. A partially
-    // signed transaction the pipeline builds is accepted by a real node, but
-    // that test runs against a local regtest node behind `BITCOIN_REGTEST=1`
-    // and never in the normal suite. The browser wallet that signs in
-    // production is driven by nothing but a mock, and no funded mainnet
-    // transfer has completed.
     endToEndProof: 'pending',
     isValidAddress: (value) => bech32Bitcoin.test(value) || base58Bitcoin.test(value),
-    // bech32 and base58 are case-significant; canonical form is the input unchanged.
     normalizeAddress: (value) => value,
     addressCasing: 'significant',
 };
@@ -85,16 +44,9 @@ const tvmDescriptor = {
     id: 'tvm',
     label: 'Tron',
     caipNamespace: 'tron',
-    // Tron native currency (TRX), as Relay expects it. Not a real contract: it is
-    // the placeholder address Relay publishes for the chain's native asset.
     nativeAssetSentinel: 'T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb',
-    // The first wallet the interface reaches outside Reown AppKit: it reads an
-    // injected provider directly. That is more of the connection path owned
-    // here, and therefore more of it unexercised outside a mock. No funded
-    // transfer has completed.
     endToEndProof: 'pending',
     isValidAddress: (value) => base58Tron.test(value),
-    // base58check is case-significant; canonical form is the input unchanged.
     normalizeAddress: (value) => value,
     addressCasing: 'significant',
 };
@@ -102,17 +54,9 @@ const tonvmDescriptor = {
     id: 'tonvm',
     label: 'The Open Network',
     caipNamespace: 'ton',
-    // Relay publishes Gram — NOT the Toncoin gas asset — as this chain's native
-    // currency, so a native-asset route on The Open Network is denominated in
-    // Gram. Kept byte-equal to Relay's own value rather than "corrected".
     nativeAssetSentinel: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
-    // The second wallet outside Reown AppKit, on a separate connection library,
-    // and the one origin whose deposit identifier is derived from the returned
-    // cell rather than handed back by the wallet. Only a mock has ever returned
-    // that cell. No funded transfer has completed.
     endToEndProof: 'pending',
     isValidAddress: (value) => friendlyTon.test(value) || rawTon.test(value),
-    // both encodings are case-significant; canonical form is the input unchanged.
     normalizeAddress: (value) => value,
     addressCasing: 'significant',
 };
@@ -120,71 +64,22 @@ const hypevmDescriptor = {
     id: 'hypevm',
     label: 'Hyperliquid',
     caipNamespace: 'hyperliquid',
-    // Relay publishes USD Coin — NOT the Hype gas asset — as this chain's native
-    // currency, and addresses it by a sixteen-byte HyperCore token identifier
-    // rather than the twenty-byte all-zero address every Ethereum Virtual Machine
-    // chain uses. The two sentinels are therefore different strings.
     nativeAssetSentinel: '0x00000000000000000000000000000000',
-    // THE WORST OF THE SIX, and the one that was actively misleading. The
-    // interface's source picker never offers Hyperliquid — nothing can quote it
-    // — yet the landing page drew a pill for it that set the source chain to
-    // Hyperliquid on click. A reader who pressed it arrived at a chain the form
-    // does not list and no provider answers. Removing the pill removes that dead
-    // end; the descriptor stays because the route layer still has to be able to
-    // NAME the chain.
     endToEndProof: 'pending',
-    // This predicate checks TOKEN addresses, and HyperCore identifies a token by a
-    // hex string SHORTER than an Ethereum address — sixteen bytes for most,
-    // nineteen for a few — so the twenty-byte `isAddress` check would reject the
-    // very identifiers it exists to accept. Its only consumer silently falls back
-    // to the native sentinel when this returns false, so an over-strict pattern
-    // would quietly swallow valid token links instead of surfacing an error.
-    // Accounts are a different namespace (ordinary twenty-byte Ethereum
-    // addresses) and are validated by the wallet layer, not here.
     isValidAddress: (value) => hyperliquidTokenId.test(value),
-    // Hex is case-insensitive and Relay emits lower case, so lower case is the
-    // canonical form. It matters: the token-equality check compares non-Ethereum
-    // addresses exactly, and only a single canonical case makes that correct.
     normalizeAddress: (value) => hyperliquidTokenId.test(value) ? value.toLowerCase() : value,
     addressCasing: 'significant',
 };
 const zcashDescriptor = {
     id: 'zcash',
     label: 'Zcash',
-    // Zcash is not a Relay chain and has no widely-registered chain-agnostic
-    // namespace. `zcash` is this repository's own key, and nothing maps a
-    // connected wallet through it, because no wallet connects to this family.
     caipNamespace: 'zcash',
-    // DERIVED, NOT INVENTED: the transparent pay-to-public-key-hash address of
-    // an all-zero key hash, base58check over the mainnet prefix `1cb8` followed
-    // by twenty zero bytes. Nobody holds a key for it. It follows the pattern of
-    // Relay's Bitcoin sentinel, an all-zero witness program, and for the same
-    // reason: the sentinel stands where a token address is expected, so it must
-    // pass this family's own address check. Zcash carries no tokens on this
-    // route, so the native asset is the only asset.
     nativeAssetSentinel: 't1Hsc1LR8yKnbbe3twRp88p6vFfC5t7DLbs',
-    // THE FIRST ECOSYSTEM WITH NO WALLET AT ALL, and therefore the first whose
-    // hold cannot be cleared by connecting one. The reader pays an address by
-    // hand from wherever they hold the coin, so every part of the journey that
-    // this repository owns — the quote, the address, the amount, the deadline,
-    // the status poll — is exercised only by a fixture. Nothing funded has
-    // crossed. Clearing this is one word, after one transfer.
     endToEndProof: 'pending',
     isValidAddress: (value) => transparentZcash.test(value),
-    // base58check is case-significant; canonical form is the input unchanged.
     normalizeAddress: (value) => value,
     addressCasing: 'significant',
 };
-/**
- * Every ecosystem the bridge can originate from. LI.FI-compatible one first.
- *
- * Registration means the library can MODEL and QUOTE the ecosystem, not that an
- * interface can sign it — see the note on {@link Ecosystem}.
- *
- * It means less than that again where a public claim is concerned: read
- * {@link EndToEndProof} before listing this registry anywhere a reader will
- * take it as an offer.
- */
 exports.ecosystemRegistry = [
     evmDescriptor,
     svmDescriptor,
@@ -195,14 +90,6 @@ exports.ecosystemRegistry = [
     zcashDescriptor,
 ];
 const byId = new Map(exports.ecosystemRegistry.map((descriptor) => [descriptor.id, descriptor]));
-/**
- * Looks up the descriptor for an ecosystem id. Total over the `Ecosystem` union;
- * throws only if the registry is ever left incomplete (a programming error the
- * round-trip test would catch).
- *
- * @param id - the ecosystem key
- * @returns the descriptor whose `id` equals `id`
- */
 const ecosystemById = (id) => {
     const descriptor = byId.get(id);
     if (descriptor === undefined) {
@@ -211,88 +98,18 @@ const ecosystemById = (id) => {
     return descriptor;
 };
 exports.ecosystemById = ecosystemById;
-/**
- * Whether a transfer has been carried through this ecosystem end to end.
- *
- * The predicate a surface calls before ADVERTISING an origin. It is separate
- * from anything the router asks, and deliberately so: the router must keep
- * quoting and naming every registered ecosystem, because a reader who reaches
- * an unproven chain through a link still needs the page to work. This governs
- * only what the product offers unprompted.
- *
- * @param id - the ecosystem key
- * @returns true when a real transfer has completed through it
- */
 const isEcosystemProvenEndToEnd = (id) => (0, exports.ecosystemById)(id).endToEndProof === 'verified';
 exports.isEcosystemProvenEndToEnd = isEcosystemProvenEndToEnd;
 const byNamespace = new Map(exports.ecosystemRegistry.map((descriptor) => [descriptor.caipNamespace, descriptor]));
-/**
- * Resolves an ecosystem from a chain-agnostic identifier namespace.
- *
- * @param namespace - the leading segment of a "namespace:reference:address" id
- * @returns the matching descriptor, or undefined when the namespace is unknown
- */
 const ecosystemByCaipNamespace = (namespace) => byNamespace.get(namespace);
 exports.ecosystemByCaipNamespace = ecosystemByCaipNamespace;
-/**
- * Whether two addresses in the same ecosystem name the same thing.
- *
- * THE ONE PLACE THIS QUESTION IS ANSWERED. It was answered in two: this
- * registry, which knows each family's address rules, and a ternary in the
- * interface's routing module that hard-coded "Ethereum is case-insensitive,
- * everything else is not". Two homes means a family added here is still
- * compared wrongly there, silently, because a loose comparison does not fail —
- * it merges two different accounts into one.
- *
- * @param a - an address
- * @param b - an address, in the same ecosystem
- * @param ecosystem - the ecosystem both belong to
- * @returns whether they are the same address
- */
 const sameAddress = (a, b, ecosystem) => (0, exports.ecosystemById)(ecosystem).addressCasing === 'insensitive'
     ? a.toLowerCase() === b.toLowerCase()
     : a === b;
 exports.sameAddress = sameAddress;
-/**
- * Whether an address is the ecosystem's own native asset rather than a token.
- *
- * Every ecosystem already declares its `nativeAssetSentinel`, and this is the
- * predicate that reads it. The comparison goes through {@link sameAddress}
- * rather than `toLowerCase()`, which matters for exactly the families where the
- * hand-written checks were wrong to begin with: Solana's, Bitcoin's and The
- * Open Network's sentinels are case-significant, so lower-casing them before
- * comparing can match an address that is not the sentinel.
- *
- * @param value - the address to test
- * @param ecosystem - the ecosystem it belongs to
- * @returns whether it names the native asset
- */
 const isNativeAsset = (value, ecosystem) => (0, exports.sameAddress)(value, (0, exports.ecosystemById)(ecosystem).nativeAssetSentinel, ecosystem);
 exports.isNativeAsset = isNativeAsset;
-/**
- * Whether a string is a well-formed address in this ecosystem.
- *
- * A free function over the registry, so a caller needs the ecosystem key and
- * nothing else. Reaching for viem's `isAddress` directly is the thing this
- * replaces: it answers only for Ethereum and answers FALSE — confidently — for
- * every valid Solana, Bitcoin, Tron and Open Network address.
- *
- * @param value - the string to test
- * @param ecosystem - the ecosystem to test it against
- * @returns whether the string is a valid address there
- */
 const isValidAddressIn = (value, ecosystem) => (0, exports.ecosystemById)(ecosystem).isValidAddress(value);
 exports.isValidAddressIn = isValidAddressIn;
-/**
- * The ecosystem's canonical spelling of an address.
- *
- * Total and side-effect-free: an input this ecosystem cannot parse comes back
- * unchanged rather than throwing, because normalizing is something callers do
- * on the way to a comparison and a throw there would be a crash on a typo.
- *
- * @param value - the address to normalize
- * @param ecosystem - the ecosystem it belongs to
- * @returns the canonical form, or the input when it cannot be parsed
- */
 const normalizeAddressIn = (value, ecosystem) => (0, exports.ecosystemById)(ecosystem).normalizeAddress(value);
 exports.normalizeAddressIn = normalizeAddressIn;

package/dist/cjs/execution.js

@@ -42,22 +42,15 @@ const consolidated_quote_js_1 = require("./consolidated-quote.js");
 const pulsex_js_1 = require("./routing/carriers/pulsex.js");
 const swap_transactions_js_1 = require("./routing/swap-transactions.js");
 const settings_js_1 = require("./settings.js");
-/**
- * An {@link AllowanceReader} that reports no allowance anywhere, so the plan
- * includes every approval. For a caller that reads allowances itself at send
- * time.
- */
 const assumeNoAllowance = async () => 0n;
 exports.assumeNoAllowance = assumeNoAllowance;
 const refusal = (value) => ({ kind: 'refused', refusal: value });
-/** The fee director a delivery choice encodes, or null when the reader buys no delivery. */
 const encodeDelivery = ({ leg, pathway, }) => {
     const { delivery } = leg;
     if (!delivery.shouldDeliver)
         return { kind: 'encoded', feeDirector: null };
     if (!pathway.requiresDelivery)
         return refusal({ reason: 'delivery-not-offered' });
-    // A zero fee pays no relayer, so the transfer would wait for a delivery that never comes.
     if (delivery.fee.maximumFee <= 0n)
         return refusal({ reason: 'delivery-fee-missing' });
     const feeDirector = (0, settings_js_1.feeDirectorStructEncoded)({
@@ -132,16 +125,6 @@ const omnibridgeCalls = (leg, account) => {
         delivery: deliveryTermsOf(leg.delivery),
     };
 };
-/**
- * The venue a swap edge was priced on, from the venues execution was given.
- * A router that is not in those venues THROWS: signing on another router, on
- * PulseX most of all, would trade against pools the reader was never shown.
- *
- * @param venues - the venues passed to execution
- * @param edge - the swap edge
- * @returns the venue
- * @throws when the edge's router is not in `venues`, or its chain has no venue
- */
 const requireSwapVenue = (venues, edge) => {
     const venue = (0, pulsex_js_1.venueForEdge)(venues, edge);
     if (venue !== null)
@@ -156,8 +139,6 @@ const pulseXSwapCalls = (leg, venues) => {
     if (edge.carrier !== 'PulseX')
         return refusal({ reason: 'swap-refused' });
     const routerAddress = requireSwapVenue(venues, edge).router;
-    // The builder refuses a hop that records no priced path, a router other
-    // than the edge's own, and a leg on screen that disagrees.
     const call = (0, swap_transactions_js_1.buildPulseXSwapTransaction)({
         hop: leg.hop,
         amountIn: leg.amountIn,
@@ -222,7 +203,6 @@ const legCalls = (leg, account, venues) => {
         return wrapCalls(leg);
     return aggregatorCalls(leg);
 };
-/** The approve transactions an approval needs now: none when the allowance on chain covers it. */
 const approvalTransactions = async ({ approval, account, readAllowance, }) => {
     const allowance = await readAllowance(approval.chainId, approval.token, account, approval.spender);
     return (0, settings_js_1.approvalAmounts)({ allowance, minimum: approval.minimum }).map((amount) => ({
@@ -232,20 +212,6 @@ const approvalTransactions = async ({ approval, account, readAllowance, }) => {
         gasLimit: null,
     }));
 };
-/**
- * Plans the transactions for a list of legs, in order.
- *
- * Each leg contributes the exact approval it needs when the allowance on
- * chain does not cover it (a reset to zero first when a smaller allowance
- * remains), then its own call. Nothing is sent.
- *
- * @param options.account - the account that signs every transaction
- * @param options.legs - the legs, in the order the wallet signs them
- * @param options.readAllowance - reads an allowance on chain; see {@link AllowanceReader}
- * @param options.swapVenues - the routers swaps may sign on, merged over the defaults; a swap whose router is in none of them throws
- * @returns the ordered transactions, or the first leg that cannot be planned
- * @throws when a swap leg's router is not in the swap venues
- */
 const planExecution = async ({ account, legs, readAllowance, swapVenues, }) => {
     const venues = (0, swap_venues_js_1.resolveSwapVenues)(swapVenues);
     const calls = legs.map((leg) => legCalls(leg, account, venues));
@@ -312,7 +278,6 @@ const pulseXSectionLeg = (hop, inputs) => {
     if (quotedAmountOut !== undefined && quotedAmountOut <= 0n) {
         return { kind: 'refused', refusal: { reason: 'swap-quote-not-positive' } };
     }
-    // Without a fresh quote the floor comes from the hop's own figure, so it must be a real quote.
     if (quotedAmountOut === undefined && hop.outcome.kind !== 'quote') {
         return { kind: 'refused', refusal: { reason: 'swap-estimate-only' } };
     }
@@ -331,7 +296,6 @@ const pulseXSectionLeg = (hop, inputs) => {
         },
     };
 };
-/** Turns one section of an engine plan into its leg, dispatching on the first hop's carrier. */
 const planSectionLeg = ({ hops, inputs, resolveToken, }) => {
     const firstHop = hops[0];
     if (firstHop === undefined)
@@ -339,8 +303,6 @@ const planSectionLeg = ({ hops, inputs, resolveToken, }) => {
     const { carrier, origin, from, to } = firstHop.edge;
     if (origin === 'by-hand')
         return { kind: 'refused', refusal: { reason: 'paid-by-hand' } };
-    // An aggregator section may run several hops inside one signature (a fused
-    // omnibridge entry); every other carrier signs exactly one hop.
     const singleHop = hops.length === 1;
     if (isOmnibridgeCarrier(carrier)) {
         if (!singleHop)
@@ -359,18 +321,7 @@ const planSectionLeg = ({ hops, inputs, resolveToken, }) => {
     }
     return aggregatorSectionLeg(carrier, inputs);
 };
-/** The sections of a plan, each as its hops. */
 const planSections = (plan) => plan.signatures.map((group) => group.flatMap((hopIndex) => plan.hops[hopIndex] ?? []));
-/**
- * A candidate built without an engine plan is one signature: either a
- * same-chain omnibridge crossing (`buildDirectCrossingCandidate`, whose quote
- * names the bridge) or an aggregator quote.
- *
- * THE CANDIDATE'S OWN QUOTE IS NEVER SIGNED. It priced the route on screen
- * and may be stale or a dry probe; only the live quote in
- * `inputs.aggregator` is. Without one the section is refused with
- * `live-quote-required`.
- */
 const planlessSectionLeg = (candidate, inputs) => {
     const provider = candidate.quote.provider;
     if (isOmnibridgeCarrier(provider)) {
@@ -384,10 +335,6 @@ const planlessSectionLeg = (candidate, inputs) => {
     }
     return aggregatorSectionLeg(provider, inputs);
 };
-/**
- * What is wrong with the requested window of sections, or null when it fits.
- * A window starts at `firstSectionIndex` and spans `plannedCount` sections.
- */
 const sectionWindowProblem = ({ firstSectionIndex, plannedCount, sectionCount, }) => {
     if (!Number.isSafeInteger(firstSectionIndex) || firstSectionIndex < 0) {
         return `firstSectionIndex must be a non-negative safe integer, received ${firstSectionIndex}`;
@@ -399,32 +346,6 @@ const sectionWindowProblem = ({ firstSectionIndex, plannedCount, sectionCount, }
     }
     return null;
 };
-/**
- * Plans the transactions for a chosen route candidate: the candidate
- * `buildRouteCandidateFromPlan` returns for an engine plan (the interface's
- * `buildCandidateFromEnginePlan`), or a candidate built without a plan.
- *
- * ONE SECTION IS ONE SIGNATURE. A plan's `signatures` groups its hops into
- * sections; the section's first hop names its carrier. An omnibridge section
- * becomes a crossing, a PulseX section a swap signed on its recorded path, a
- * wrap section a wrap or unwrap, and any other wallet-signed carrier an
- * aggregator deposit from the live quote the caller supplies. A section paid
- * by hand has nothing to sign and is refused.
- *
- * A LATER SECTION CAN BE PLANNED ALONE. Pass `firstSectionIndex` to skip the
- * sections that already landed. The wallet then plans the swap after the
- * crossing arrived, from the amount that arrived, with a fresh
- * `swap.quotedAmountOut` and a fresh `swap.deadline`. The slippage floor and the
- * deadline are not fixed minutes before the swap is signed. Every safety check
- * still applies to the later section: verified spenders, live quotes for
- * aggregator sections, exact approvals.
- *
- * Every `sectionIndex` in a refusal and every `legIndex` in `deliveries` is
- * the absolute section index.
- *
- * @param inputs - see {@link CandidateExecutionInputs}
- * @returns the ordered transactions with the deliveries they buy, or the first section that cannot be planned
- */
 const planCandidateExecution = async (inputs) => {
     const { candidate, account, readAllowance, resolveToken, sections, swapVenues } = inputs;
     const firstSectionIndex = inputs.firstSectionIndex ?? 0;
@@ -461,19 +382,6 @@ const planCandidateExecution = async (inputs) => {
     };
 };
 exports.planCandidateExecution = planCandidateExecution;
-/**
- * Reads a fresh quote for a PulseX section: what the router's `getAmountsOut`
- * says the swap delivers for `amountIn`, along the exact path the swap signs
- * ({@link pulseXSwapPathForHop}) on the edge's own router. A wallet passes the
- * result as `swap.quotedAmountOut` just before it signs.
- *
- * @param options.hop - the swap hop; its recorded path and edge name what to read
- * @param options.amountIn - the amount the swap spends, in base units
- * @param options.client - a client that can call `readContract`
- * @param options.swapVenues - the routers swaps may sign on, merged over the defaults
- * @returns the amount the last token of the path delivers, or null when the hop records no path, the amount is not positive, or the read fails or returns nothing
- * @throws when the hop records a path but its router is not in the swap venues
- */
 const readPulseXSectionQuote = async ({ hop, amountIn, client, swapVenues, }) => {
     const path = (0, pulsex_js_1.pulseXSwapPathForHop)(hop);
     if (path === null || amountIn <= 0n)

package/dist/cjs/fee-type.js

@@ -6,5 +6,4 @@ exports.feeTypeValToKeyMap = exports.FeeType = void 0;
     FeeType["GAS_TIP"] = "gas+%";
     FeeType["FIXED"] = "fixed";
 })(exports.FeeType || (exports.FeeType = {}));
-/** A map of fee type values to keys */
 exports.feeTypeValToKeyMap = new Map(Object.keys(exports.FeeType).map((key) => [exports.FeeType[key], key]));