@gibs/bridge-sdk 1.13.1 → 1.18.0

package/dist/consolidated-quote.js

@@ -1,21 +1,27 @@
+import { buildQuery, buildUrl, isHttpUrl } from '@gibs/common/url';
+import { decodeFunctionData, erc20Abi, parseAbi, zeroAddress } from 'viem';
 import { Chains } from './config.js';
-import { LifiExecutionRefusedError, verifyLifiEvmExecution, } from './lifi-execution-guard.js';
+import { LifiExecutionRefusedError, lifiDiamondAddressByChainId, verifyLifiEvmExecution, } from './lifi-execution-guard.js';
 import { depositFamilyOf, isEvmDeposit, } from './origin-deposit.js';
 import { lifiQuoteFees } from './quote-fees.js';
 import { referralIntegrator, resolveAttribution } from './referral.js';
 import { normalizeLifiSteps } from './route-steps.js';
+import { relayDepositoryByChainId } from './relay-depository.js';
 /**
- * The LI.FI `integrator` sent when a request leaves
- * {@link ConsolidatedQuoteRequest.lifiIntegrator} out.
+ * Gibs Finance's own LI.FI `integrator` label.
  *
- * KEPT AS A DEFAULT BECAUSE IT COSTS THE CALLER NOTHING. LI.FI's `integrator`
- * is an optional label: it changes neither the quote nor the rate limit, and it
- * moves no money unless a `fee` rides with it. A fee is the one case where the
- * label decides who gets paid, so a request that charges a fee must name its
- * own integrator — see {@link lifiAttribution}.
+ * NOT A DEFAULT. A request that leaves
+ * {@link ConsolidatedQuoteRequest.lifiIntegrator} out sends no `integrator`
+ * at all. An integrator label is attribution: LI.FI records the traffic under
+ * it, and pays any `fee` to the account behind it. A wallet that builds on this
+ * package must not attribute its users' routes to Gibs Finance without
+ * choosing to. The Gibs interface passes this value explicitly.
  */
 export const lifiIntegrator = referralIntegrator;
-/** Referral fee charged by this integrator on LI.FI routes (0.001 = 0.1%). */
+/**
+ * The referral fee Gibs Finance charges on its own LI.FI routes (0.001 = 0.1%).
+ * No builder applies it. A request carries a fee only when it sets `lifiFee`.
+ */
 export const lifiReferralFeePercent = 0.001;
 /**
  * LI.FI's HTTP origin when the interface's `PUBLIC_LIFI_API_URL` build flag is
@@ -24,15 +30,6 @@ export const lifiReferralFeePercent = 0.001;
  * at LI.FI's shared, unauthenticated tier — with no configuration at all.
  */
 export const lifiDefaultApiOrigin = 'https://li.quest';
-const isAbsoluteHttpUrl = (value) => {
-    try {
-        const url = new URL(value);
-        return url.protocol === 'http:' || url.protocol === 'https:';
-    }
-    catch {
-        return false;
-    }
-};
 /**
  * Builds every LI.FI endpoint address from one origin — THE ONE PLACE the
  * `/v1/...` paths are spelled, so a caller pointed at a different origin (the
@@ -48,7 +45,7 @@ const isAbsoluteHttpUrl = (value) => {
  * @returns a frozen object of every endpoint this codebase calls
  */
 export const lifiEndpoints = (apiOrigin) => {
-    if (!isAbsoluteHttpUrl(apiOrigin)) {
+    if (!isHttpUrl(apiOrigin)) {
         throw new Error(`lifiEndpoints: "${apiOrigin}" is not an absolute http(s) origin`);
     }
     const base = `${apiOrigin.replace(/\/+$/, '')}/v1`;
@@ -56,22 +53,12 @@ export const lifiEndpoints = (apiOrigin) => {
         quote: `${base}/quote`,
         contractCallsQuote: `${base}/quote/contractCalls`,
         chains: `${base}/chains`,
-        tokens: (chainId) => {
-            const url = new URL(`${base}/tokens`);
-            url.searchParams.set('chains', chainId.toString());
-            return url.toString();
-        },
-        status: ({ txHash, fromChainId, toChainId }) => {
-            const url = new URL(`${base}/status`);
-            url.searchParams.set('txHash', txHash);
-            if (fromChainId !== undefined) {
-                url.searchParams.set('fromChain', fromChainId.toString());
-            }
-            if (toChainId !== undefined) {
-                url.searchParams.set('toChain', toChainId.toString());
-            }
-            return url.toString();
-        },
+        tokens: (chainId) => buildUrl(`${base}/tokens`, { chains: chainId.toString() }),
+        status: ({ txHash, fromChainId, toChainId }) => buildUrl(`${base}/status`, {
+            txHash,
+            fromChain: fromChainId?.toString(),
+            toChain: toChainId?.toString(),
+        }),
     });
 };
 const defaultLifiEndpoints = lifiEndpoints(lifiDefaultApiOrigin);
@@ -139,16 +126,16 @@ export const isNonEthereumVirtualMachineOrigin = (request) => (request.originVmT
  * @param request - the consolidated request's attribution fields
  * @returns the fields to merge into the request; empty when none apply
  * @throws when a positive `lifiFee` arrives without an explicit `lifiIntegrator`
- *   string — that fee would otherwise be paid to the default integrator
+ *   string — LI.FI would have nobody of yours to pay it to
  */
 export const lifiAttribution = (request) => {
-    const integrator = resolveAttribution(request.lifiIntegrator, lifiIntegrator);
+    const integrator = resolveAttribution(request.lifiIntegrator, undefined);
     const chargesFee = request.lifiFee !== undefined && request.lifiFee > 0;
     if (!chargesFee) {
         return integrator === undefined ? {} : { integrator };
     }
     if (typeof request.lifiIntegrator !== 'string') {
-        throw new Error('lifiFee needs an explicit lifiIntegrator: LI.FI pays the fee to the integrator label, and the default label is not yours');
+        throw new Error('lifiFee needs an explicit lifiIntegrator: LI.FI pays the fee to the account behind the integrator label');
     }
     return { integrator: request.lifiIntegrator, fee: request.lifiFee };
 };
@@ -200,7 +187,10 @@ export const buildLifiQuoteRequest = (request) => {
     if ((request.originVmType ?? 'evm') !== 'evm') {
         return null;
     }
-    const params = new URLSearchParams({
+    // Same attribution as the contract-calls builder, so a fee the reader agreed
+    // to is charged on both endpoints, not only on one.
+    const { integrator, fee } = lifiAttribution(request);
+    return buildQuery({
         fromChain: request.fromChainId.toString(),
         toChain: toChainId.toString(),
         fromToken: request.fromTokenAddress,
@@ -211,20 +201,11 @@ export const buildLifiQuoteRequest = (request) => {
         // same account for an ordinary transfer and are NOT when a reader has named
         // a delivery address, which is exactly the case a bridge has to get right.
         toAddress: request.recipient,
+        // Each optional parameter is left out when it is undefined.
+        integrator,
+        fee: fee?.toString(),
+        slippage: request.slippage?.toString(),
     });
-    // Same attribution as the contract-calls builder, so a fee the reader agreed
-    // to is charged on both endpoints, not only on one.
-    const { integrator, fee } = lifiAttribution(request);
-    if (integrator !== undefined) {
-        params.set('integrator', integrator);
-    }
-    if (fee !== undefined) {
-        params.set('fee', fee.toString());
-    }
-    if (request.slippage !== undefined) {
-        params.set('slippage', request.slippage.toString());
-    }
-    return params.toString();
 };
 export const buildLifiContractCallsRequest = (request) => {
     const { destinationCall, toAmount } = request;
@@ -286,6 +267,282 @@ export const evmDepositOf = (quote) => {
     }
     return quote.originDeposit;
 };
+const refuseOrigin = (refusal) => ({ kind: 'refused', refusal });
+const sameHexAddress = (a, b) => a.toLowerCase() === b.toLowerCase();
+/**
+ * The amount of the origin token the reader sends, in base units.
+ *
+ * THE REQUEST IS THE AUTHORITY. A route with no omnibridge entry call is
+ * solved forwards: the reader names the input and the request carries it as
+ * `fromAmount`. {@link aggregatorOriginCalls} refuses a quote whose own
+ * `fromAmount` differs from it.
+ *
+ * A route WITH an entry call is solved backwards from an exact output, so the
+ * request names no input at all and the provider works one out. For that
+ * route the quote's `fromAmount` is the only figure there is. The deposit, the
+ * approval and the quote must still agree with each other, but no figure of
+ * the reader's exists to compare them with.
+ */
+const amountToSendOf = ({ quote, request }) => request.fromAmount ?? quote.fromAmount;
+const refuseAmount = ({ provider, field, expected, actual, }) => refuseVerdict({ reason: 'amount-mismatch', provider, field, expected, actual });
+const refuseRecipient = ({ provider, field, expected, actual, }) => refuseVerdict({ reason: 'recipient-mismatch', provider, field, expected, actual });
+const refuseVerdict = (refusal) => ({ kind: 'refused', refusal });
+/**
+ * The spender a provider allows, given the one contract it trusts on this
+ * chain: no approval when the quote asks for none, the trusted contract when
+ * the quote names it, and a refusal for any other address.
+ */
+const spenderVerdict = ({ provider, requested, trusted, }) => {
+    if (requested === null)
+        return { kind: 'verified', spender: null };
+    if (trusted === null || !sameHexAddress(requested, trusted)) {
+        return refuseVerdict({ reason: 'spender-not-allowed', provider, spender: requested });
+    }
+    // The one place a spender is branded verified: the trusted table entry.
+    return { kind: 'verified', spender: trusted };
+};
+/**
+ * LI.FI: the deposit and the spender must be LI.FI's Diamond, and the calldata
+ * must say what was asked: the receiver, the asset, and (through
+ * `originAmount`) the exact amount pulled from the reader.
+ */
+const lifiOriginVerdict = ({ request, quote, deposit, amountToSend }) => {
+    const diamond = lifiDiamondAddressByChainId.get(deposit.chainId);
+    if (diamond === undefined)
+        return refuseVerdict({ reason: 'unverified-chain', provider: 'lifi', chainId: deposit.chainId });
+    try {
+        verifyLifiEvmExecution(deposit, quote.approvalAddress, {
+            ...lifiExecutionExpectation(request),
+            originAmount: amountToSend,
+        });
+    }
+    catch (error) {
+        if (error instanceof LifiExecutionRefusedError)
+            return refuseVerdict({ reason: 'lifi-guard', detail: error.refusal.detail });
+        throw error;
+    }
+    return spenderVerdict({ provider: 'lifi', requested: quote.approvalAddress, trusted: diamond });
+};
+/**
+ * The two deposit functions Relay's depository exposes, as observed in live
+ * `POST /quote/v2` answers on 2026-10-07 (Ethereum to Base):
+ *
+ * - `depositNative(address depositor, bytes32 id)` (selector `0x49290c1c`):
+ *   the amount is `msg.value`; the calldata carries NO amount.
+ * - `depositErc20(address depositor, address token, uint256 amount, bytes32 id)`
+ *   (selector `0xe8017952`): the calldata carries the token and the amount.
+ *
+ * Any other selector is refused rather than guessed at.
+ */
+const relayDepositoryAbi = parseAbi([
+    'function depositNative(address depositor, bytes32 id) payable',
+    'function depositErc20(address depositor, address token, uint256 amount, bytes32 id)',
+]);
+const decodeRelayDeposit = (data) => {
+    try {
+        return decodeFunctionData({ abi: relayDepositoryAbi, data });
+    }
+    catch {
+        return null;
+    }
+};
+/** The native half of Relay's deposit: `depositNative`, with the amount as `msg.value`. */
+const relayNativeVerdict = ({ deposit, amountToSend }) => {
+    const provider = 'relay';
+    if (deposit.value !== amountToSend) {
+        return refuseAmount({ provider, field: 'deposit-value', expected: amountToSend, actual: deposit.value });
+    }
+    const decoded = decodeRelayDeposit(deposit.data);
+    if (decoded === null || decoded.functionName !== 'depositNative') {
+        return refuseVerdict({ reason: 'deposit-shape', provider, detail: 'a native deposit is not depositNative' });
+    }
+    return null;
+};
+/** The token half of Relay's deposit: no value, and `depositErc20` naming the request's token and amount. */
+const relayTokenVerdict = ({ request, deposit, amountToSend }) => {
+    const provider = 'relay';
+    if (deposit.value !== 0n) {
+        return refuseAmount({ provider, field: 'deposit-value', expected: 0n, actual: deposit.value });
+    }
+    const decoded = decodeRelayDeposit(deposit.data);
+    if (decoded === null || decoded.functionName !== 'depositErc20') {
+        return refuseVerdict({ reason: 'deposit-shape', provider, detail: 'a token deposit is not depositErc20' });
+    }
+    const [, token, amount] = decoded.args;
+    if (!sameHexAddress(token, request.fromTokenAddress)) {
+        return refuseRecipient({ provider, field: 'calldata-token', expected: request.fromTokenAddress, actual: token });
+    }
+    if (amount !== amountToSend) {
+        return refuseAmount({ provider, field: 'calldata-amount', expected: amountToSend, actual: amount });
+    }
+    return null;
+};
+/**
+ * Relay: the deposit and the spender must be Relay's depository on the
+ * deposit's chain, and the deposit must move exactly the amount to send.
+ *
+ * - A native origin: `value` equals the amount, and the calldata is
+ *   `depositNative`, which carries no amount of its own.
+ * - A token origin: `value` is 0, and the calldata is `depositErc20` for the
+ *   request's token and the amount, decoded with {@link relayDepositoryAbi}.
+ *
+ * The depositor and the order identifier inside the calldata are NOT checked.
+ * The identifier is Relay's own, and nothing in the request predicts it.
+ */
+const relayOriginVerdict = (inputs) => {
+    const { quote, request, deposit } = inputs;
+    const depository = relayDepositoryByChainId.get(deposit.chainId);
+    if (depository === undefined) {
+        return refuseVerdict({ reason: 'unverified-chain', provider: 'relay', chainId: deposit.chainId });
+    }
+    if (!sameHexAddress(deposit.to, depository)) {
+        return refuseVerdict({ reason: 'deposit-target-not-allowed', provider: 'relay', target: deposit.to });
+    }
+    const spender = spenderVerdict({ provider: 'relay', requested: quote.approvalAddress, trusted: depository });
+    if (spender.kind === 'refused')
+        return spender;
+    const refusal = request.fromTokenAddress === zeroAddress ? relayNativeVerdict(inputs) : relayTokenVerdict(inputs);
+    return refusal ?? spender;
+};
+const decodeTransfer = (data) => {
+    try {
+        return decodeFunctionData({ abi: erc20Abi, data });
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * NEAR Intents: no contract pulls anything. The deposit is a plain payment to
+ * the quote's own deposit address, so the check is on its SHAPE and on the two
+ * figures that matter: who is paid and how much.
+ *
+ * - No approval.
+ * - A native origin: no calldata, `to` is the quote's deposit address
+ *   (`quote.quoteId`, which `parseNearIntentsQuote` sets to it), and `value`
+ *   is the amount to send.
+ * - A token origin: no value, `to` is the origin token, and the calldata is the
+ *   token's own `transfer(depositAddress, amount)` for the same two figures.
+ *
+ * The deposit address itself is per quote and cannot be checked against a
+ * fixed table; the checks bind the payment to the address the quote names.
+ */
+const nearIntentsOriginVerdict = ({ quote, request, deposit, amountToSend }) => {
+    const provider = 'near-intents';
+    // NEAR Intents trusts no spender at all.
+    const spender = spenderVerdict({ provider, requested: quote.approvalAddress, trusted: null });
+    if (spender.kind === 'refused')
+        return spender;
+    if (request.fromTokenAddress === zeroAddress) {
+        if (deposit.data !== '0x')
+            return refuseVerdict({ reason: 'deposit-shape', provider, detail: 'a native deposit carries calldata' });
+        if (!sameHexAddress(deposit.to, quote.quoteId)) {
+            return refuseRecipient({ provider, field: 'deposit-to', expected: quote.quoteId, actual: deposit.to });
+        }
+        if (deposit.value !== amountToSend) {
+            return refuseAmount({ provider, field: 'deposit-value', expected: amountToSend, actual: deposit.value });
+        }
+        return spender;
+    }
+    if (!sameHexAddress(deposit.to, request.fromTokenAddress)) {
+        return refuseVerdict({ reason: 'deposit-target-not-allowed', provider, target: deposit.to });
+    }
+    if (deposit.value !== 0n)
+        return refuseAmount({ provider, field: 'deposit-value', expected: 0n, actual: deposit.value });
+    const decoded = decodeTransfer(deposit.data);
+    if (decoded === null || decoded.functionName !== 'transfer') {
+        return refuseVerdict({ reason: 'deposit-shape', provider, detail: 'a token deposit is not a plain transfer' });
+    }
+    const [payee, amount] = decoded.args;
+    if (!sameHexAddress(payee, quote.quoteId)) {
+        return refuseRecipient({ provider, field: 'transfer-to', expected: quote.quoteId, actual: payee });
+    }
+    if (amount !== amountToSend) {
+        return refuseAmount({ provider, field: 'calldata-amount', expected: amountToSend, actual: amount });
+    }
+    return spender;
+};
+const originVerdictByProvider = {
+    lifi: lifiOriginVerdict,
+    relay: relayOriginVerdict,
+    'near-intents': nearIntentsOriginVerdict,
+};
+/**
+ * Reads the approval and the deposit off an aggregator quote with an Ethereum
+ * origin, after checking both against what this code knows about the
+ * provider. The interface's aggregator press (`stores/consolidated-execute.ts`)
+ * and the SDK's execution planner both read them here, so neither can sign a
+ * call the other would refuse.
+ *
+ * WHAT IS CHECKED, BEFORE ANYTHING IS APPROVED OR SENT:
+ * - Every provider: when the request names the amount to send
+ *   (`request.fromAmount`), the quote's own `fromAmount` must equal it.
+ * - LI.FI: `verifyLifiEvmExecution`: the Diamond for the chain, a known
+ *   facet call, calldata that matches the request, and the decoded amount
+ *   pulled from the reader equal to the amount to send.
+ * - Relay: the deposit target and the spender are Relay's depository for the
+ *   chain (`relayDepositoryByChainId`). A native deposit carries the amount
+ *   as `value` through `depositNative`; a token deposit carries no value and
+ *   is `depositErc20` for the request's token and the amount.
+ * - NEAR Intents: no spender, and a plain payment of the amount to send to the
+ *   quote's own deposit address (`quote.quoteId`), native or `transfer`.
+ * - Any other provider is refused. Its spender is unknown.
+ *
+ * The approval is for exactly the amount to send (the request's, else the
+ * quote's when the route is solved backwards and the request names none), on
+ * the request's origin chain. The native coin needs none.
+ *
+ * @param options.quote - the live quote to sign
+ * @param options.request - the request it answered
+ * @returns the checked approval and deposit, or why they are refused
+ */
+export const aggregatorOriginCalls = ({ quote, request, }) => {
+    const { originDeposit } = quote;
+    if (!isEvmDeposit(originDeposit)) {
+        return refuseOrigin({ reason: 'not-evm-deposit', depositFamily: depositFamilyOf(originDeposit) });
+    }
+    if (originDeposit.chainId !== request.fromChainId) {
+        return refuseOrigin({
+            reason: 'chain-mismatch',
+            depositChainId: originDeposit.chainId,
+            requestChainId: request.fromChainId,
+        });
+    }
+    const check = originVerdictByProvider[quote.provider];
+    if (check === undefined)
+        return refuseOrigin({ reason: 'unverified-provider', provider: quote.provider });
+    const amountToSend = amountToSendOf({ quote, request });
+    if (amountToSend !== quote.fromAmount) {
+        return refuseOrigin({
+            reason: 'amount-mismatch',
+            provider: quote.provider,
+            field: 'quote-from-amount',
+            expected: amountToSend,
+            actual: quote.fromAmount,
+        });
+    }
+    const verdict = check({ quote, request, deposit: originDeposit, amountToSend });
+    if (verdict.kind === 'refused')
+        return refuseOrigin(verdict.refusal);
+    // THE SPENDER COMES FROM THE VERDICT, never from `quote.approvalAddress`:
+    // only an address the provider check took from its own table can be
+    // approved, so no provider path can forget the check.
+    if (request.fromTokenAddress === zeroAddress || verdict.spender === null) {
+        return { kind: 'calls', approval: null, deposit: originDeposit };
+    }
+    return {
+        kind: 'calls',
+        approval: {
+            chainId: request.fromChainId,
+            // An Ethereum origin; the request widens the address to `string` only
+            // for non-Ethereum origins, which were refused above.
+            token: request.fromTokenAddress,
+            spender: verdict.spender,
+            minimum: amountToSend,
+        },
+        deposit: originDeposit,
+    };
+};
 const isHexString = (value) => typeof value === 'string' && value.startsWith('0x');
 /**
  * Parses the ecosystem-independent part of a LI.FI quote.
@@ -382,6 +639,7 @@ const lifiExecutionExpectation = (request) => {
         sendingAssetId: request.fromTokenAddress,
         hasDestinationCall,
         minimumAmount: hasDestinationCall ? request.toAmount : null,
+        originAmount: request.fromAmount ?? null,
     };
 };
 /**