@gibs/bridge-sdk 1.13.1 → 1.17.0

package/dist/execution.js

@@ -0,0 +1,428 @@
+import { zeroAddress } from 'viem';
+import * as abis from './abis.js';
+import { Providers, toChain } from './config.js';
+import { aggregatorOriginCalls, } from './consolidated-quote.js';
+import { pulseXRouterForEdge, pulseXSwapPathForHop } 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),
+    };
+};
+const pulseXSwapCalls = (leg) => {
+    const { edge } = leg.hop;
+    const chainId = edge.from.chainId;
+    const routerAddress = pulseXRouterForEdge(edge);
+    // 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,
+    });
+    if (call === null || routerAddress === 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) => {
+    if (leg.kind === 'omnibridge')
+        return omnibridgeCalls(leg, account);
+    if (leg.kind === 'pulsex-swap')
+        return pulseXSwapCalls(leg);
+    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}
+ * @returns the ordered transactions, or the first leg that cannot be planned
+ */
+export const planExecution = async ({ account, legs, readAllowance, }) => {
+    const calls = legs.map((leg) => legCalls(leg, account));
+    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 } = 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 });
+    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`
+ * @returns the amount the last token of the path delivers, or null when the hop records no path, names no known router, the amount is not positive, or the read fails or returns nothing
+ */
+export const readPulseXSectionQuote = async ({ hop, amountIn, client, }) => {
+    const path = pulseXSwapPathForHop(hop);
+    const router = pulseXRouterForEdge(hop.edge);
+    if (path === null || router === null || amountIn <= 0n)
+        return null;
+    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

@@ -18,3 +18,6 @@ export * from './route-steps.js';
 export * from './routing/index.js';
 export * from './settings.js';
 export * from './types.js';
+export * from './claims.js';
+export * from './execution.js';
+export * from './relay-depository.js';

package/dist/index.js

@@ -18,3 +18,6 @@ export * from './route-steps.js';
 export * from './routing/index.js';
 export * from './settings.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/providers.d.ts

@@ -132,6 +132,23 @@ export type ProviderDescriptor = {
      * `providers.test.ts`).
      */
     destinationCallCarriesNativeValue: boolean;
+    /**
+     * How this provider takes an Ethereum token from the reader's wallet.
+     *
+     * - `'allowance'` — the provider's contract pulls the token, so the wallet
+     *   must first approve that contract as a spender. The execution quote names
+     *   the spender (`ConsolidatedQuote.approvalAddress`), and the executor
+     *   raises the allowance before it sends.
+     * - `'transfer'` — the reader sends the token to an address the provider
+     *   gives. A plain transfer needs no approval, and the parser leaves
+     *   `approvalAddress` null.
+     *
+     * A DISPLAY FACT, NEVER A SIGNING ONE. The press reads the live quote's own
+     * `approvalAddress` and the live allowance. This field lets a route say, BEFORE
+     * any live quote exists, that its wallet may ask for an approval first.
+     * The native coin never needs one, whatever this says.
+     */
+    originTokenSpend: 'allowance' | 'transfer';
     /**
      * Phase one: the plain forward-solving origin-to-anchor swap pre-quote.
      *

package/dist/providers.js

@@ -11,6 +11,8 @@ const lifiDescriptor = {
     executesDestinationCalls: true,
     destinationCallOriginChainIds: [Number(Chains.ETH)],
     destinationCallCarriesNativeValue: false,
+    // Its quote names the Diamond as `estimate.approvalAddress`.
+    originTokenSpend: 'allowance',
     preQuote: {
         method: 'GET',
         build: buildLifiPreQuoteRequest,
@@ -33,6 +35,8 @@ const relayDescriptor = {
     executesDestinationCalls: true,
     destinationCallOriginChainIds: 'any',
     destinationCallCarriesNativeValue: true,
+    // Its quote carries an approve step; the parser lifts its spender.
+    originTokenSpend: 'allowance',
     preQuote: {
         method: 'POST',
         build: buildRelayPreQuoteRequest,
@@ -61,6 +65,8 @@ const nearIntentsDescriptor = {
     executesDestinationCalls: false,
     destinationCallOriginChainIds: [],
     destinationCallCarriesNativeValue: false,
+    // The reader sends the token to a deposit address.
+    originTokenSpend: 'transfer',
     preQuote: {
         method: 'POST',
         build: buildNearIntentsPreQuoteRequest,

package/dist/referral.d.ts

@@ -34,7 +34,11 @@ export declare const referralIntegrator = "gibs.finance";
  */
 export declare const resolveAttribution: (override: string | null | undefined, packageDefault: string | undefined) => string | undefined;
 /**
- * Payout address for Relay application fees.
+ * Gibs Finance's payout address for Relay application fees.
+ *
+ * NO BUILDER APPLIES IT. A Relay request carries an `appFees` entry only when
+ * the caller passes `relayAppFee`. The Gibs interface passes this address
+ * explicitly; any other caller passes its own, or nothing.
  *
  * Set to the owner's receiving wallet. Setting it back to `null` is a working
  * state rather than a broken one, and is the way to stop collecting: Relay
@@ -53,9 +57,13 @@ export declare const resolveAttribution: (override: string | null | undefined, p
  */
 export declare const relayReferralRecipient: Hex | null;
 /**
- * Default application fee in basis points. Ten basis points is one tenth of one
- * percent. The interface can override it per provider in stored settings; this
- * is the value a reader who has never touched the setting gets.
+ * The application fee the Gibs interface charges, in basis points. Ten basis
+ * points is one tenth of one percent. The interface can override it per
+ * provider in stored settings; this is the value a reader who has never touched
+ * the setting gets.
+ *
+ * NO BUILDER APPLIES IT. It reaches a request only when a caller passes it as
+ * `relayAppFee.basisPoints` (Relay) or converts it to `lifiFee` (LI.FI).
  */
 export declare const defaultReferralFeeBasisPoints = 10n;
 /**