@gibs/bridge-sdk 1.13.1 → 1.18.0

package/dist/execution.js

@@ -0,0 +1,455 @@
+import { zeroAddress } from 'viem';
+import * as abis from './abis.js';
+import { Providers, toChain } from './config.js';
+import { resolveSwapVenues } from './swap-venues.js';
+import { aggregatorOriginCalls, } from './consolidated-quote.js';
+import { pulseXSwapPathForHop, venueForEdge } from './routing/carriers/pulsex.js';
+import { buildPulseXSwapTransaction, buildWrapTransaction, swapMinimumOut } from './routing/swap-transactions.js';
+import { approvalAmounts, approveCall, bridgePathway, destinationDataParam, feeDirectorStructEncoded, feeTypeSettings, omnibridgeApproval, transactionInputs, } from './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.
+ */
+export const assumeNoAllowance = async () => 0n;
+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 = feeDirectorStructEncoded({
+        recipient: leg.recipient,
+        bridgePathway: pathway,
+        feeType: delivery.fee.feeType,
+        priceCorrective: delivery.fee.priceCorrective,
+        gasTipFee: delivery.fee.gasTipFee,
+        percentFee: delivery.fee.percentFee,
+        feeTypeSettings: feeTypeSettings({ feeType: delivery.fee.feeType, unwrap: leg.unwrap }),
+        limit: delivery.fee.maximumFee,
+        assetOut: delivery.fee.assetOut,
+    });
+    if (feeDirector === null)
+        return refusal({ reason: 'delivery-fee-unencodable' });
+    return { kind: 'encoded', feeDirector };
+};
+const deliveryTermsOf = (delivery) => {
+    if (!delivery.shouldDeliver)
+        return { status: 'not-requested' };
+    return {
+        status: 'requested',
+        feeType: delivery.fee.feeType,
+        maximumFee: delivery.fee.maximumFee,
+        feeToken: delivery.fee.assetOut,
+    };
+};
+const omnibridgeCalls = (leg, account) => {
+    if (leg.amountIn <= 0n)
+        return refusal({ reason: 'amount-not-positive' });
+    const pathway = bridgePathway({ bridgeKey: leg.bridgeKey, isProd: leg.isProd, assetIn: leg.assetIn });
+    if (pathway === null)
+        return refusal({ reason: 'no-pathway' });
+    const encoded = encodeDelivery({ leg, pathway });
+    if (encoded.kind !== 'encoded')
+        return encoded;
+    const { feeDirector } = encoded;
+    const dataParam = destinationDataParam({
+        recipient: leg.recipient,
+        bridgePathway: pathway,
+        assetIn: leg.assetIn,
+        destinationRouter: pathway.destinationRouter,
+        feeDirectorStructEncoded: feeDirector,
+        assetLink: leg.assetLink,
+        shouldDeliver: leg.delivery.shouldDeliver,
+        unwrap: leg.unwrap,
+    });
+    const call = transactionInputs({
+        bridgeKey: leg.bridgeKey,
+        signedCrossing: { originChainId: Number(leg.bridgeKey[1]), destinationChainId: Number(leg.bridgeKey[2]) },
+        bridgePathway: pathway,
+        assetIn: leg.assetIn,
+        recipient: leg.recipient,
+        account,
+        assetLink: leg.assetLink,
+        destinationDataParam: dataParam,
+        amountToBridge: leg.amountIn,
+        feeDirectorStructEncoded: feeDirector,
+        shouldDeliver: leg.delivery.shouldDeliver,
+    });
+    if (call === null)
+        return refusal({ reason: 'bridge-call-refused' });
+    return {
+        kind: 'calls',
+        approval: omnibridgeApproval({
+            bridgePathway: pathway,
+            assetIn: leg.assetIn,
+            assetLink: leg.assetLink,
+            amountToBridge: leg.amountIn,
+        }),
+        action: { chainId: Number(leg.bridgeKey[1]), kind: 'bridge', ...call, gasLimit: null },
+        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 = venueForEdge(venues, edge);
+    if (venue !== null)
+        return venue;
+    const router = edge.venue ?? 'the default router';
+    throw new Error(`The swap was priced on ${router} on chain ${edge.from.chainId}, but that router is not in the swap venues passed to execution. ` +
+        'Pass the same swapVenues the route search used.');
+};
+const pulseXSwapCalls = (leg, venues) => {
+    const { edge } = leg.hop;
+    const chainId = edge.from.chainId;
+    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 = buildPulseXSwapTransaction({
+        hop: leg.hop,
+        amountIn: leg.amountIn,
+        minAmountOut: leg.minAmountOut,
+        recipient: leg.recipient,
+        deadline: leg.deadline,
+        signedLeg: { kind: 'swap', chainId },
+        chainId,
+        routerAddress,
+        venues,
+    });
+    if (call === null)
+        return refusal({ reason: 'swap-refused' });
+    const spendsNative = edge.from.address.toLowerCase() === zeroAddress;
+    return {
+        kind: 'calls',
+        approval: spendsNative
+            ? null
+            : { chainId, token: edge.from.address, spender: routerAddress, minimum: leg.amountIn },
+        action: { chainId, kind: 'swap', ...call, gasLimit: null },
+        delivery: null,
+    };
+};
+const wrapCalls = (leg) => {
+    const call = buildWrapTransaction({ edge: leg.edge, amountIn: leg.amountIn });
+    if (call === null)
+        return refusal({ reason: 'wrap-refused' });
+    const wraps = leg.edge.from.address.toLowerCase() === zeroAddress;
+    return {
+        kind: 'calls',
+        approval: null,
+        action: { chainId: leg.edge.from.chainId, kind: wraps ? 'wrap' : 'unwrap', ...call, gasLimit: null },
+        delivery: null,
+    };
+};
+const aggregatorCalls = (leg) => {
+    const origin = aggregatorOriginCalls({ quote: leg.quote, request: leg.request });
+    if (origin.kind === 'refused')
+        return refusal({ reason: 'aggregator-origin-refused', origin: origin.refusal });
+    const { approval, deposit } = origin;
+    const staysOnChain = leg.request.toChainId === leg.request.fromChainId;
+    return {
+        kind: 'calls',
+        approval,
+        action: {
+            chainId: leg.request.fromChainId,
+            kind: staysOnChain ? 'swap' : 'bridge',
+            to: deposit.to,
+            data: deposit.data,
+            value: deposit.value,
+            gasLimit: deposit.gasLimit,
+        },
+        delivery: null,
+    };
+};
+const legCalls = (leg, account, venues) => {
+    if (leg.kind === 'omnibridge')
+        return omnibridgeCalls(leg, account);
+    if (leg.kind === 'pulsex-swap')
+        return pulseXSwapCalls(leg, venues);
+    if (leg.kind === 'wrap')
+        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 approvalAmounts({ allowance, minimum: approval.minimum }).map((amount) => ({
+        chainId: approval.chainId,
+        kind: 'approve',
+        ...approveCall({ token: approval.token, spender: approval.spender, amount }),
+        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
+ */
+export const planExecution = async ({ account, legs, readAllowance, swapVenues, }) => {
+    const venues = resolveSwapVenues(swapVenues);
+    const calls = legs.map((leg) => legCalls(leg, account, venues));
+    const refusedIndex = calls.findIndex((entry) => entry.kind === 'refused');
+    const refused = calls[refusedIndex];
+    if (refused !== undefined && refused.kind === 'refused') {
+        return { kind: 'refused', legIndex: refusedIndex, refusal: refused.refusal };
+    }
+    const planned = calls.flatMap((entry) => (entry.kind === 'calls' ? [entry] : []));
+    const perLeg = await Promise.all(planned.map(async (entry) => {
+        const approvals = entry.approval === null
+            ? []
+            : await approvalTransactions({ approval: entry.approval, account, readAllowance });
+        return [...approvals, entry.action];
+    }));
+    const ordered = perLeg.flat();
+    const transactions = ordered.map((action, index) => ({ ...action, waitForReceipt: index < ordered.length - 1 }));
+    const deliveries = planned.flatMap((entry, legIndex) => entry.delivery === null ? [] : [{ ...entry.delivery, legIndex }]);
+    return { kind: 'planned', transactions, deliveries };
+};
+const OMNIBRIDGE_CARRIERS = new Set(Object.values(Providers));
+const isOmnibridgeCarrier = (carrier) => OMNIBRIDGE_CARRIERS.has(carrier);
+const missing = (needs) => ({
+    kind: 'refused',
+    refusal: { reason: 'section-inputs-missing', needs },
+});
+const shape = (detail) => ({ kind: 'refused', refusal: { reason: 'section-shape', detail } });
+const omnibridgeSectionLeg = ({ carrier, from, to, inputs, assetIn, }) => {
+    if (inputs.omnibridge === undefined)
+        return missing('omnibridge');
+    return {
+        kind: 'leg',
+        leg: {
+            kind: 'omnibridge',
+            bridgeKey: [carrier, toChain(from.chainId), toChain(to.chainId)],
+            isProd: inputs.omnibridge.isProd,
+            assetIn,
+            assetLink: inputs.omnibridge.assetLink,
+            amountIn: inputs.amountIn,
+            recipient: inputs.recipient,
+            delivery: inputs.omnibridge.delivery,
+            unwrap: inputs.omnibridge.unwrap,
+        },
+    };
+};
+const liveQuoteRequired = { kind: 'refused', refusal: { reason: 'live-quote-required' } };
+const aggregatorSectionLeg = (carrier, inputs) => {
+    if (inputs.aggregator === undefined)
+        return liveQuoteRequired;
+    const { quote, request } = inputs.aggregator;
+    if (quote.provider !== carrier) {
+        return {
+            kind: 'refused',
+            refusal: { reason: 'quote-provider-mismatch', quoteProvider: quote.provider, sectionCarrier: carrier },
+        };
+    }
+    return { kind: 'leg', leg: { kind: 'aggregator', quote, request } };
+};
+const pulseXSectionLeg = (hop, inputs) => {
+    if (inputs.swap === undefined)
+        return missing('swap');
+    const { quotedAmountOut } = inputs.swap;
+    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' } };
+    }
+    return {
+        kind: 'leg',
+        leg: {
+            kind: 'pulsex-swap',
+            hop,
+            amountIn: inputs.amountIn,
+            minAmountOut: swapMinimumOut({
+                quotedAmount: quotedAmountOut ?? hop.outcome.deliveredAmount,
+                slippageBasisPoints: inputs.swap.slippageBasisPoints,
+            }),
+            recipient: inputs.recipient,
+            deadline: inputs.swap.deadline,
+        },
+    };
+};
+/** 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)
+        return shape('the section has no hops');
+    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)
+            return shape('an omnibridge section is exactly one hop');
+        return omnibridgeSectionLeg({ carrier, from, to, inputs, assetIn: resolveToken(from) });
+    }
+    if (carrier === 'PulseX') {
+        if (!singleHop)
+            return shape('a swap section is exactly one hop');
+        return pulseXSectionLeg(firstHop, inputs);
+    }
+    if (carrier === 'wrap') {
+        if (!singleHop)
+            return shape('a wrap section is exactly one hop');
+        return { kind: 'leg', leg: { kind: 'wrap', edge: firstHop.edge, amountIn: inputs.amountIn } };
+    }
+    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)) {
+        return omnibridgeSectionLeg({
+            carrier: provider,
+            from: candidate.originToken,
+            to: candidate.destinationToken,
+            inputs,
+            assetIn: candidate.originToken,
+        });
+    }
+    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}`;
+    }
+    if (plannedCount < 1)
+        return `pass at least 1 section input, received ${plannedCount}`;
+    if (firstSectionIndex + plannedCount > sectionCount) {
+        return `sections ${firstSectionIndex} to ${firstSectionIndex + plannedCount - 1} do not fit a route of ${sectionCount} section${sectionCount === 1 ? '' : 's'}`;
+    }
+    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
+ */
+export const planCandidateExecution = async (inputs) => {
+    const { candidate, account, readAllowance, resolveToken, sections, swapVenues } = inputs;
+    const firstSectionIndex = inputs.firstSectionIndex ?? 0;
+    const plan = candidate.plan;
+    const allSections = plan === undefined ? null : planSections(plan);
+    const sectionCount = allSections === null ? 1 : allSections.length;
+    const problem = sectionWindowProblem({ firstSectionIndex, plannedCount: sections.length, sectionCount });
+    if (problem !== null) {
+        const validIndex = Number.isSafeInteger(firstSectionIndex) && firstSectionIndex >= 0;
+        return {
+            kind: 'refused',
+            sectionIndex: validIndex ? firstSectionIndex : 0,
+            refusal: { reason: 'section-shape', detail: problem },
+        };
+    }
+    const sectionLegs = sections.map((sectionInputs, index) => allSections === null
+        ? planlessSectionLeg(candidate, sectionInputs)
+        : planSectionLeg({ hops: allSections[firstSectionIndex + index] ?? [], inputs: sectionInputs, resolveToken }));
+    const refusedIndex = sectionLegs.findIndex((entry) => entry.kind === 'refused');
+    const refused = sectionLegs[refusedIndex];
+    if (refused !== undefined && refused.kind === 'refused') {
+        return { kind: 'refused', sectionIndex: firstSectionIndex + refusedIndex, refusal: refused.refusal };
+    }
+    const legs = sectionLegs.flatMap((entry) => (entry.kind === 'leg' ? [entry.leg] : []));
+    const planned = await planExecution({ account, legs, readAllowance, ...(swapVenues === undefined ? {} : { swapVenues }) });
+    if (planned.kind === 'refused') {
+        return { kind: 'refused', sectionIndex: firstSectionIndex + planned.legIndex, refusal: planned.refusal };
+    }
+    return {
+        kind: 'planned',
+        transactions: planned.transactions,
+        deliveries: planned.deliveries.map((delivery) => ({ ...delivery, legIndex: firstSectionIndex + delivery.legIndex })),
+        remainingSectionCount: sectionCount - firstSectionIndex - sections.length,
+    };
+};
+/**
+ * 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
+ */
+export const readPulseXSectionQuote = async ({ hop, amountIn, client, swapVenues, }) => {
+    const path = pulseXSwapPathForHop(hop);
+    if (path === null || amountIn <= 0n)
+        return null;
+    const router = requireSwapVenue(resolveSwapVenues(swapVenues), hop.edge).router;
+    try {
+        const amounts = await client.readContract({
+            address: router,
+            abi: abis.univ2Router,
+            functionName: 'getAmountsOut',
+            args: [amountIn, path],
+        });
+        return amounts.at(-1) ?? null;
+    }
+    catch {
+        return null;
+    }
+};

package/dist/hyperliquid-execution.js

@@ -1,3 +1,4 @@
+import { buildUrl } from '@gibs/common/url';
 import { parseSignature } from 'viem';
 import { relayApiBaseUrl } from './relay-quote.js';
 /**
@@ -158,10 +159,8 @@ export const buildHyperliquidAuthorizationRequest = ({ authorization, signature,
     if (!endpoint.startsWith('/')) {
         return null;
     }
-    const url = new URL(`${baseUrl}${endpoint}`);
-    url.searchParams.set('signature', signature);
     return {
-        url: url.href,
+        url: buildUrl(`${baseUrl}${endpoint}`, { signature }),
         method,
         body: { ...body, signatureChainId },
     };

package/dist/index.d.ts

@@ -17,4 +17,8 @@ export * from './referral.js';
 export * from './route-steps.js';
 export * from './routing/index.js';
 export * from './settings.js';
+export * from './swap-venues.js';
 export * from './types.js';
+export * from './claims.js';
+export * from './execution.js';
+export * from './relay-depository.js';

package/dist/index.js

@@ -17,4 +17,8 @@ export * from './referral.js';
 export * from './route-steps.js';
 export * from './routing/index.js';
 export * from './settings.js';
+export * from './swap-venues.js';
 export * from './types.js';
+export * from './claims.js';
+export * from './execution.js';
+export * from './relay-depository.js';

package/dist/lifi-execution-guard.d.ts

@@ -77,12 +77,13 @@ import { type Hex } from 'viem';
  * `receiver-mismatch`, `destination-chain-mismatch`, `sending-asset-mismatch`,
  * `destination-call-flag-mismatch` and `minimum-amount-below-requested`
  * distrust `data`'s DECODED fields against what this application asked for;
- * `native-value-mismatch` distrusts `value`. `missing-request-context` is
+ * `origin-amount-mismatch` distrusts the decoded amount pulled from the
+ * depositor; `native-value-mismatch` distrusts `value`. `missing-request-context` is
  * different in kind: it means the CALLER never supplied what this
  * application expected, so none of the above could even be checked — see
  * `parseLifiContractCallsQuote` and `parseLifiQuote` in `consolidated-quote.ts`.
  */
-export type LifiExecutionRefusalReason = 'unknown-chain' | 'router-mismatch' | 'approval-address-mismatch' | 'unknown-selector' | 'calldata-undecodable' | 'receiver-mismatch' | 'destination-chain-mismatch' | 'sending-asset-mismatch' | 'destination-call-flag-mismatch' | 'minimum-amount-below-requested' | 'native-value-mismatch' | 'missing-request-context';
+export type LifiExecutionRefusalReason = 'unknown-chain' | 'router-mismatch' | 'approval-address-mismatch' | 'unknown-selector' | 'calldata-undecodable' | 'receiver-mismatch' | 'destination-chain-mismatch' | 'sending-asset-mismatch' | 'destination-call-flag-mismatch' | 'minimum-amount-below-requested' | 'origin-amount-mismatch' | 'native-value-mismatch' | 'missing-request-context';
 /** Why a LI.FI execution transaction was refused before signing. */
 export type LifiExecutionRefusal = {
     readonly reason: LifiExecutionRefusalReason;
@@ -174,6 +175,16 @@ export type LifiExecutionExpectation = {
      * of constrained by the request. See `ConsolidatedQuote.toAmount`.
      */
     readonly minimumAmount: bigint | null;
+    /**
+     * The exact amount of the origin token this application sends, in base units,
+     * or `null` when the request names none.
+     *
+     * Compared with the decoded `swapData[0].fromAmount`, the amount pulled from
+     * the depositor. Without it a response could keep every other field honest and
+     * still pull more than the reader chose. The request, never the response,
+     * supplies this figure.
+     */
+    readonly originAmount: bigint | null;
 };
 /** The transaction fields {@link verifyLifiEvmExecution} reads off the raw response. */
 export type LifiExecutionTransactionRequest = {

package/dist/lifi-execution-guard.js

@@ -389,6 +389,10 @@ export const verifyLifiEvmExecution = (transactionRequest, approvalAddress, expe
             return;
         }
     }
+    if (expectation.originAmount !== null && decoded.originAmount !== expectation.originAmount) {
+        refuse('origin-amount-mismatch', `decoded origin amount (${decoded.originAmount}) does not equal the amount to send (${expectation.originAmount})`);
+        return;
+    }
     const nativeOriginComponent = sameAddress(decoded.originSendingAssetId, zeroAddress)
         ? decoded.originAmount
         : 0n;

package/dist/near-intents.js

@@ -1,3 +1,4 @@
+import { buildUrl } from '@gibs/common/url';
 import { arbitrum, avalanche, base, bsc, gnosis, mainnet, optimism, polygon, scroll, } from 'viem/chains';
 import { encodeFunctionData, erc20Abi, isAddress } from 'viem';
 import { depositAddressChainIds, isDepositAddressChain, relayChainIds, } from './chain-names.js';
@@ -102,9 +103,7 @@ export const nearIntentsAuthenticatedStablecoinFeeBasisPoints = 1;
  * @returns the fully-formed status address
  */
 export const nearIntentsStatusUrl = ({ quoteId }) => {
-    const url = new URL(`${nearIntentsApiBaseUrl}/v0/status`);
-    url.searchParams.set('depositAddress', quoteId);
-    return url.toString();
+    return buildUrl(`${nearIntentsApiBaseUrl}/v0/status`, { depositAddress: quoteId });
 };
 /**
  * What this repository calls itself when it asks the one-click service.

package/dist/pre-quote.d.ts

@@ -82,12 +82,12 @@ export type PreQuoteRequest = {
      */
     relayReferrer?: string | null;
     /**
-     * Overrides the `integrator` sent to LI.FI: `undefined` defaults to
-     * {@link lifiIntegrator} (a free attribution label, `gibs.finance`),
-     * `null` OMITS the `integrator` query parameter entirely (it is optional
-     * per LI.FI's own `/v1/quote` schema — verified 2026-09-23 — an empty
-     * string is not "absent", it is a literal empty integrator), and a string
-     * is sent as-is.
+     * The `integrator` sent to LI.FI. Left out or `null`, the query parameter is
+     * OMITTED entirely (it is optional per LI.FI's own `/v1/quote` schema —
+     * verified 2026-09-23 — and an empty string would be a literal empty
+     * integrator, not an absent one). A string is sent as-is. Gibs Finance's own
+     * label is `lifiIntegrator` in `consolidated-quote.ts`; it is never sent
+     * unless you pass it.
      */
     lifiIntegrator?: string | null;
 };

package/dist/pre-quote.js

@@ -1,4 +1,5 @@
-import { isNonEthereumVirtualMachineOrigin, lifiIntegrator, } from './consolidated-quote.js';
+import { buildQuery } from '@gibs/common/url';
+import { isNonEthereumVirtualMachineOrigin, } from './consolidated-quote.js';
 import { resolveAttribution } from './referral.js';
 import { relayReferrerField, slippageToBasisPoints, } from './relay-quote.js';
 /**
@@ -84,26 +85,21 @@ export const buildLifiPreQuoteRequest = (request) => {
     if (isNonEthereumVirtualMachineOrigin(request)) {
         return null;
     }
-    const params = new URLSearchParams({
+    // Left out or `null` OMITS the query parameter (LI.FI's own schema marks it
+    // optional); a string is sent as-is. No package default: attribution is the
+    // caller's to choose. See `PreQuoteRequest.lifiIntegrator`'s doc.
+    const integrator = resolveAttribution(request.lifiIntegrator, undefined);
+    return buildQuery({
         fromChain: request.fromChainId.toString(),
         toChain: request.toChainId.toString(),
         fromToken: request.fromTokenAddress,
         toToken: request.toTokenAddress,
         fromAmount: request.amount.toString(),
         fromAddress: request.fromAddress,
+        // Each optional parameter is left out when it is undefined.
+        integrator,
+        slippage: request.slippage?.toString(),
     });
-    // `null` means "no integrator of this caller's own" and OMITS the query
-    // parameter (LI.FI's own schema marks it optional); `undefined` means
-    // "this repository's own default"; a string is sent as-is. See
-    // `PreQuoteRequest.lifiIntegrator`'s doc.
-    const integrator = resolveAttribution(request.lifiIntegrator, lifiIntegrator);
-    if (integrator !== undefined) {
-        params.set('integrator', integrator);
-    }
-    if (request.slippage !== undefined) {
-        params.set('slippage', request.slippage.toString());
-    }
-    return params.toString();
 };
 const asRecord = (value) => {
     if (typeof value !== 'object' || value === null) {

package/dist/prices.d.ts

@@ -105,3 +105,13 @@ export declare const resolveTokenPriceUsd: (token: Token, { pulsexPrices, lifiPr
     pulsexPrices: Map<string, number>;
     lifiPrices: Map<string, number>;
 }) => number | null;
+/**
+ * The chain's canonical wrapped native address when `token` is the native
+ * coin (zero address) or that wrapper itself, and null for every other token.
+ * Only the SAME chain's pair is returned: a bridged copy of a wrapper on
+ * another chain is a different token and keeps its own price.
+ *
+ * @param token - the token to test
+ * @returns the wrapped native address on the token's own chain, or null
+ */
+export declare const sameChainWrappedNative: (token: Token) => Hex | null;