@anywalletkit/protocol-swap2-core 0.10.3 → 0.11.0

package/dist/swap2/base.d.cts

@@ -45,6 +45,35 @@ declare const NATIVE_DECIMALS: Readonly<Record<string, number>>;
 declare function nativeDecimals(chain: string): number;
 /** `whole` native coins (an integer, or a decimal string such as "0.005") in `chain`'s base units. */
 declare function nativeUnits(chain: string, whole: number | string): bigint;
+/**
+ * The hard maximum of {@link Swap2EngineConfig.nativeFeeCeiling}: it may name at most this many times the chain's
+ * default cap (0.1 ETH on Ethereum and the ETH-denominated L2s, 2000 CELO on Celo). A value above it is refused, so a
+ * units slip (wei for gwei, an extra zero) or a "no limit" sentinel cannot switch the ceiling off.
+ */
+declare const NATIVE_FEE_CEILING_MAX_MULTIPLE = 20n;
+/** What {@link Swap2EngineConfig.nativeFeeCeiling} is asked about: the native fee one execution's quote declares. */
+interface Swap2NativeFeeCeilingContext {
+    /**
+     * The provider the route came from, e.g. `"usdt0"`: the name it is installed under (the router binds every quote to
+     * its provider's name, so a quote cannot claim another venue's).
+     */
+    readonly provider: string;
+    /**
+     * The quote's intent id as the provider wrote it, e.g. `"usdt0-mesh:30101:30420"` (USDT0 Legacy Mesh, Ethereum →
+     * Tron). Through a swap2 server (`remoteProvider`) it ends in `~<token>`: match its start.
+     */
+    readonly intentId: string;
+    /** CAIP-2 of the source chain, where the fee is paid (`"eip155:1"`). */
+    readonly fromChain: string;
+    /** CAIP-2 of the destination in the catalog form: Tron is `"tron:728126428"` whichever form the app passed. */
+    readonly destChain: string;
+    /** The native fee the quote declares, in base units of the source chain's native coin. */
+    readonly nativeFee: bigint;
+    /** The engine's own cap for `fromChain`: what applies when the hook returns `undefined`. */
+    readonly defaultCap: bigint;
+    /** The most the hook may return: {@link NATIVE_FEE_CEILING_MAX_MULTIPLE} × `defaultCap`. */
+    readonly maxCeiling: bigint;
+}
 type Swap2ExecutionPhase = "approving" | "requoting" | "preflight" | "signing" | "broadcast";
 interface Swap2ExecutionPhaseDetail {
     /** approving: which approval of how many (USDT on Ethereum needs two). */
@@ -85,6 +114,36 @@ interface Swap2EngineConfig extends Swap2ProtocolConfig {
      * refused (scan 2026-10-27 modules, F7).
      */
     tonGasCeiling?: bigint | number | string;
+    /**
+     * The app's native-fee ceiling for a route. A route may charge native coin on top of the input (a bridge's messaging
+     * fee, declared by the quote); the engine refuses a fee above its per-chain cap (0.005 ETH on Ethereum and on chains
+     * without a row, 100 CELO on Celo, …). This hook is asked for every execution pass whose quote declares a native fee, before
+     * that pass's review and approvals (once, unless the quote expires during an approval and the engine re-quotes: the
+     * fresh quote is asked again; a refusal then revokes the allowance just granted):
+     *
+     * - a non-negative `bigint` is the cap for that execution, in place of the chain's own (higher or lower; `0n` refuses
+     *   any fee). It may be at most {@link NATIVE_FEE_CEILING_MAX_MULTIPLE} × the chain's cap (`ctx.maxCeiling`);
+     * - `undefined` keeps the chain's cap, exactly as without the hook;
+     * - anything else (a number, a string, `null`, a Promise), a value above `ctx.maxCeiling`, or a throw refuses the
+     *   execution (`Swap2ConfigurationError`). There is no answer that removes the cap. The option itself is a function or
+     *   left out: any other value (`null` included) refuses every execution that declares a native fee.
+     *
+     * Route policy is the app's: match the provider, the destination and the intent id, and leave every other route to
+     * the default. USDT0 Legacy Mesh into Tron (LayerZero eid 30420; its fee, 0.0053 ETH / 170 CELO on 2026-11-12 plus
+     * the provider's 25 % headroom, is above the default caps):
+     *
+     * ```ts
+     * const TRON_MESH = new Map([["eip155:1", 10n ** 16n], ["eip155:42161", 10n ** 16n], ["eip155:42220", 300n * 10n ** 18n]]);
+     * nativeFeeCeiling: ({provider, intentId, fromChain, destChain}) =>
+     *   provider === "usdt0" && destChain === "tron:728126428" && /^usdt0-mesh:\d+:30420(?:~|$)/.test(intentId)
+     *     ? TRON_MESH.get(fromChain) // 0.01 ETH on Ethereum and Arbitrum, 300 CELO on Celo; other sources: the default
+     *     : undefined
+     * ```
+     *
+     * Only execution (`swap2()`) applies a native-fee cap: `quoteSwap2` and the router's route list do not check one, so
+     * they list a route whose fee is above the cap, and its `swap2()` refuses it.
+     */
+    nativeFeeCeiling?: (ctx: Swap2NativeFeeCeilingContext) => bigint | undefined;
     /**
      * Review gate: called once the live quote is built and every payload/value
      * check has passed, BEFORE any approval or signature. It receives a copy of
@@ -326,4 +385,4 @@ declare abstract class BaseSwap2Protocol extends Swap2Protocol {
     getSupportedTokens(options?: Swap2SupportedTokensOptions): Promise<Swap2SupportedToken[]>;
 }
 
-export { BaseSwap2Protocol, NATIVE_DECIMALS, SWAP2_CHAIN_ALIASES, SWAP2_ID_PREFIX, type SerializedExecutionExpectation, type Swap2Account, type Swap2EngineConfig, type Swap2ExecutionPhase, type Swap2ExecutionPhaseDetail, type Swap2ExecutionPlan, type TonBodySummary, nativeDecimals, nativeUnits, normalizeTypedDomain, swap2ChainId };
+export { BaseSwap2Protocol, NATIVE_DECIMALS, NATIVE_FEE_CEILING_MAX_MULTIPLE, SWAP2_CHAIN_ALIASES, SWAP2_ID_PREFIX, type SerializedExecutionExpectation, type Swap2Account, type Swap2EngineConfig, type Swap2ExecutionPhase, type Swap2ExecutionPhaseDetail, type Swap2ExecutionPlan, type Swap2NativeFeeCeilingContext, type TonBodySummary, nativeDecimals, nativeUnits, normalizeTypedDomain, swap2ChainId };

package/dist/swap2/base.d.ts

@@ -45,6 +45,35 @@ declare const NATIVE_DECIMALS: Readonly<Record<string, number>>;
 declare function nativeDecimals(chain: string): number;
 /** `whole` native coins (an integer, or a decimal string such as "0.005") in `chain`'s base units. */
 declare function nativeUnits(chain: string, whole: number | string): bigint;
+/**
+ * The hard maximum of {@link Swap2EngineConfig.nativeFeeCeiling}: it may name at most this many times the chain's
+ * default cap (0.1 ETH on Ethereum and the ETH-denominated L2s, 2000 CELO on Celo). A value above it is refused, so a
+ * units slip (wei for gwei, an extra zero) or a "no limit" sentinel cannot switch the ceiling off.
+ */
+declare const NATIVE_FEE_CEILING_MAX_MULTIPLE = 20n;
+/** What {@link Swap2EngineConfig.nativeFeeCeiling} is asked about: the native fee one execution's quote declares. */
+interface Swap2NativeFeeCeilingContext {
+    /**
+     * The provider the route came from, e.g. `"usdt0"`: the name it is installed under (the router binds every quote to
+     * its provider's name, so a quote cannot claim another venue's).
+     */
+    readonly provider: string;
+    /**
+     * The quote's intent id as the provider wrote it, e.g. `"usdt0-mesh:30101:30420"` (USDT0 Legacy Mesh, Ethereum →
+     * Tron). Through a swap2 server (`remoteProvider`) it ends in `~<token>`: match its start.
+     */
+    readonly intentId: string;
+    /** CAIP-2 of the source chain, where the fee is paid (`"eip155:1"`). */
+    readonly fromChain: string;
+    /** CAIP-2 of the destination in the catalog form: Tron is `"tron:728126428"` whichever form the app passed. */
+    readonly destChain: string;
+    /** The native fee the quote declares, in base units of the source chain's native coin. */
+    readonly nativeFee: bigint;
+    /** The engine's own cap for `fromChain`: what applies when the hook returns `undefined`. */
+    readonly defaultCap: bigint;
+    /** The most the hook may return: {@link NATIVE_FEE_CEILING_MAX_MULTIPLE} × `defaultCap`. */
+    readonly maxCeiling: bigint;
+}
 type Swap2ExecutionPhase = "approving" | "requoting" | "preflight" | "signing" | "broadcast";
 interface Swap2ExecutionPhaseDetail {
     /** approving: which approval of how many (USDT on Ethereum needs two). */
@@ -85,6 +114,36 @@ interface Swap2EngineConfig extends Swap2ProtocolConfig {
      * refused (scan 2026-10-27 modules, F7).
      */
     tonGasCeiling?: bigint | number | string;
+    /**
+     * The app's native-fee ceiling for a route. A route may charge native coin on top of the input (a bridge's messaging
+     * fee, declared by the quote); the engine refuses a fee above its per-chain cap (0.005 ETH on Ethereum and on chains
+     * without a row, 100 CELO on Celo, …). This hook is asked for every execution pass whose quote declares a native fee, before
+     * that pass's review and approvals (once, unless the quote expires during an approval and the engine re-quotes: the
+     * fresh quote is asked again; a refusal then revokes the allowance just granted):
+     *
+     * - a non-negative `bigint` is the cap for that execution, in place of the chain's own (higher or lower; `0n` refuses
+     *   any fee). It may be at most {@link NATIVE_FEE_CEILING_MAX_MULTIPLE} × the chain's cap (`ctx.maxCeiling`);
+     * - `undefined` keeps the chain's cap, exactly as without the hook;
+     * - anything else (a number, a string, `null`, a Promise), a value above `ctx.maxCeiling`, or a throw refuses the
+     *   execution (`Swap2ConfigurationError`). There is no answer that removes the cap. The option itself is a function or
+     *   left out: any other value (`null` included) refuses every execution that declares a native fee.
+     *
+     * Route policy is the app's: match the provider, the destination and the intent id, and leave every other route to
+     * the default. USDT0 Legacy Mesh into Tron (LayerZero eid 30420; its fee, 0.0053 ETH / 170 CELO on 2026-11-12 plus
+     * the provider's 25 % headroom, is above the default caps):
+     *
+     * ```ts
+     * const TRON_MESH = new Map([["eip155:1", 10n ** 16n], ["eip155:42161", 10n ** 16n], ["eip155:42220", 300n * 10n ** 18n]]);
+     * nativeFeeCeiling: ({provider, intentId, fromChain, destChain}) =>
+     *   provider === "usdt0" && destChain === "tron:728126428" && /^usdt0-mesh:\d+:30420(?:~|$)/.test(intentId)
+     *     ? TRON_MESH.get(fromChain) // 0.01 ETH on Ethereum and Arbitrum, 300 CELO on Celo; other sources: the default
+     *     : undefined
+     * ```
+     *
+     * Only execution (`swap2()`) applies a native-fee cap: `quoteSwap2` and the router's route list do not check one, so
+     * they list a route whose fee is above the cap, and its `swap2()` refuses it.
+     */
+    nativeFeeCeiling?: (ctx: Swap2NativeFeeCeilingContext) => bigint | undefined;
     /**
      * Review gate: called once the live quote is built and every payload/value
      * check has passed, BEFORE any approval or signature. It receives a copy of
@@ -326,4 +385,4 @@ declare abstract class BaseSwap2Protocol extends Swap2Protocol {
     getSupportedTokens(options?: Swap2SupportedTokensOptions): Promise<Swap2SupportedToken[]>;
 }
 
-export { BaseSwap2Protocol, NATIVE_DECIMALS, SWAP2_CHAIN_ALIASES, SWAP2_ID_PREFIX, type SerializedExecutionExpectation, type Swap2Account, type Swap2EngineConfig, type Swap2ExecutionPhase, type Swap2ExecutionPhaseDetail, type Swap2ExecutionPlan, type TonBodySummary, nativeDecimals, nativeUnits, normalizeTypedDomain, swap2ChainId };
+export { BaseSwap2Protocol, NATIVE_DECIMALS, NATIVE_FEE_CEILING_MAX_MULTIPLE, SWAP2_CHAIN_ALIASES, SWAP2_ID_PREFIX, type SerializedExecutionExpectation, type Swap2Account, type Swap2EngineConfig, type Swap2ExecutionPhase, type Swap2ExecutionPhaseDetail, type Swap2ExecutionPlan, type Swap2NativeFeeCeilingContext, type TonBodySummary, nativeDecimals, nativeUnits, normalizeTypedDomain, swap2ChainId };

package/dist/swap2/base.js

@@ -1,19 +1,21 @@
 import {
   BaseSwap2Protocol,
   NATIVE_DECIMALS,
+  NATIVE_FEE_CEILING_MAX_MULTIPLE,
   SWAP2_CHAIN_ALIASES,
   SWAP2_ID_PREFIX,
   nativeDecimals,
   nativeUnits,
   normalizeTypedDomain,
   swap2ChainId
-} from "../chunk-2YDSKVIL.js";
+} from "../chunk-MVEAEYYJ.js";
 import "../chunk-IVR3SREQ.js";
 import "../chunk-F5TRF52T.js";
 import "../chunk-2KC734UX.js";
 export {
   BaseSwap2Protocol,
   NATIVE_DECIMALS,
+  NATIVE_FEE_CEILING_MAX_MULTIPLE,
   SWAP2_CHAIN_ALIASES,
   SWAP2_ID_PREFIX,
   nativeDecimals,

package/dist/swap2/single.cjs

@@ -295,12 +295,62 @@ var NATIVE_FEE_CAP = Object.freeze({
   // 0.1 HYPE
 });
 var DEFAULT_NATIVE_FEE_CAP = 5000000000000000n;
-function declaredNativeFee(q, chain) {
+var NATIVE_FEE_CEILING_MAX_MULTIPLE = 20n;
+function describeCeilingAnswer(value) {
+  if (value === null) return "null";
+  if (typeof value === "bigint") return String(value);
+  if (typeof value === "string") return `the string "${value.slice(0, 40)}"`;
+  if (typeof value === "number" || typeof value === "boolean") return `the ${typeof value} ${String(value)}`;
+  if (typeof value === "function") return "a function";
+  let thenable = false;
+  try {
+    thenable = typeof value.then === "function";
+    if (thenable) value.then(void 0, () => {
+    });
+  } catch {
+  }
+  return thenable ? "a Promise (the hook must answer synchronously)" : typeof value === "object" ? "an object" : `a ${typeof value}`;
+}
+function nativeFeeCap(chain, fee, route) {
+  const defaultCap = NATIVE_FEE_CAP[chain] ?? DEFAULT_NATIVE_FEE_CAP;
+  const hook = route?.ceiling;
+  if (hook === void 0) return defaultCap;
+  const maxCeiling = defaultCap * NATIVE_FEE_CEILING_MAX_MULTIPLE;
+  const where = `${route.provider} ${chain} \u2192 ${route.destChain}`;
+  if (typeof hook !== "function") {
+    throw new Swap2ConfigurationError(`swap2: nativeFeeCeiling is ${describeCeilingAnswer(hook)}, not a function \u2014 the native fee of ${where} is refused`);
+  }
+  const ctx = Object.freeze({
+    provider: route.provider,
+    intentId: route.intentId,
+    fromChain: chain,
+    destChain: route.destChain,
+    nativeFee: fee,
+    defaultCap,
+    maxCeiling
+  });
+  let answer;
+  try {
+    answer = hook(ctx);
+  } catch (error) {
+    const why = (error instanceof Error ? error.message : String(error)).slice(0, 160);
+    throw new Swap2ConfigurationError(`swap2: nativeFeeCeiling threw for ${where} (${why}) \u2014 the native fee is refused`, { cause: error });
+  }
+  if (answer === void 0) return defaultCap;
+  if (typeof answer !== "bigint" || answer < 0n) {
+    throw new Swap2ConfigurationError(`swap2: nativeFeeCeiling returned ${describeCeilingAnswer(answer)} for ${where}, not a non-negative bigint or undefined \u2014 the native fee is refused`);
+  }
+  if (answer > maxCeiling) {
+    throw new Swap2ConfigurationError(`swap2: nativeFeeCeiling returned ${answer} for ${where}, above the hard maximum ${maxCeiling} (${NATIVE_FEE_CEILING_MAX_MULTIPLE} \xD7 the default cap ${defaultCap}) \u2014 the native fee is refused`);
+  }
+  return answer;
+}
+function declaredNativeFee(q, chain, route) {
   const raw = q.txRequest?.nativeFee;
   if (raw === void 0) return 0n;
   if (!/^\d+$/.test(raw)) throw new Error("swap2: quote declares a malformed native fee");
   const fee = BigInt(raw);
-  const cap = NATIVE_FEE_CAP[chain] ?? DEFAULT_NATIVE_FEE_CAP;
+  const cap = nativeFeeCap(chain, fee, route);
   if (fee > cap) throw new Error(`swap2: quoted native fee ${fee} exceeds the cap ${cap} for ${chain}`);
   return fee;
 }
@@ -924,16 +974,18 @@ var BaseSwap2Protocol = class extends import_core.Swap2Protocol {
     const source = this.sourceAsset(executionOptions);
     if (!source) throw new Error(`swap2: unknown source token '${executionOptions.fromToken}' on ${this.fromChain}`);
     const executionValue = BigInt(unsigned.value);
+    const ceiling = this._config.nativeFeeCeiling;
+    const feeRoute = { provider: q.provider, intentId: q.intentId, destChain: params.destChain, ...ceiling !== void 0 ? { ceiling } : {} };
     if (serialized) {
       if (executionValue !== (source.contract ? 0n : BigInt(q.sourceAmount))) {
         throw new Error("swap2: provider execution amount does not match the validated quote");
       }
     } else if (source.contract && this.fromChain.startsWith("eip155:")) {
-      const declared = declaredNativeFee(q, this.fromChain);
+      const declared = declaredNativeFee(q, this.fromChain, feeRoute);
       if (executionValue !== declared) {
         throw new Error(declared === 0n ? "swap2: token execution attempted to attach native value" : `swap2: token execution value ${executionValue} does not match the quoted native fee ${declared}`);
       }
-    } else if (!unsigned.typedData && !unsigned.bodyBoc && executionValue !== BigInt(q.sourceAmount) + declaredNativeFee(q, this.fromChain)) {
+    } else if (!unsigned.typedData && !unsigned.bodyBoc && executionValue !== BigInt(q.sourceAmount) + declaredNativeFee(q, this.fromChain, feeRoute)) {
       throw new Error("swap2: provider execution amount does not match the validated quote");
     }
     let tonBody;
@@ -942,13 +994,13 @@ var BaseSwap2Protocol = class extends import_core.Swap2Protocol {
         throw new Swap2ValidationError(`swap2: TON cell-body build refused \u2014 ${why}`);
       };
       const raw = this._config.tonGasCeiling;
-      const ceiling = raw === void 0 ? DEFAULT_TON_GAS_CEILING : BigInt(raw);
-      if (ceiling < 0n) throw new Swap2ConfigurationError("swap2: tonGasCeiling must be non-negative");
+      const ceiling2 = raw === void 0 ? DEFAULT_TON_GAS_CEILING : BigInt(raw);
+      if (ceiling2 < 0n) throw new Swap2ConfigurationError("swap2: tonGasCeiling must be non-negative");
       if (provider.remote === true && provider.verifiesBuilds !== true) refuse("a remote provider's cell body needs the app's own validator (remoteProvider verifyBuild)");
       tonBody = readTonBody(cellBody);
       const input = BigInt(q.sourceAmount);
       if (source.contract) {
-        if (executionValue > ceiling) refuse(`it attaches ${executionValue} nanoTON to a jetton transfer, more than the ${ceiling} gas ceiling`);
+        if (executionValue > ceiling2) refuse(`it attaches ${executionValue} nanoTON to a jetton transfer, more than the ${ceiling2} gas ceiling`);
         const t = tonBody.jettonTransfer;
         if (!t) refuse("a jetton-source body must be a jetton transfer");
         if (t.amount !== input) refuse(`the jetton transfer moves ${t.amount}, not the swap's ${input}`);
@@ -958,7 +1010,7 @@ var BaseSwap2Protocol = class extends import_core.Swap2Protocol {
         if (!own) refuse("the account cannot name its own jetton wallet (getJettonWalletAddress), so the target cannot be checked");
         if (tonRawAddress(unsigned.to) !== own) refuse(`it is sent to ${unsigned.to}, not this account's ${source.symbol ?? "source"} jetton wallet`);
       } else {
-        if (executionValue < input || executionValue - input > ceiling) refuse(`it attaches ${executionValue} nanoTON for a ${input} input, more than the ${ceiling} gas ceiling on top`);
+        if (executionValue < input || executionValue - input > ceiling2) refuse(`it attaches ${executionValue} nanoTON for a ${input} input, more than the ${ceiling2} gas ceiling on top`);
         const pinned = provider.remote === true ? [...provider.callTargets?.(this.fromChain) ?? [], ...q.depositAddress ? [q.depositAddress] : []].map(tonRawAddress).filter((a) => !!a) : [];
         if (pinned.length && !pinned.includes(tonRawAddress(unsigned.to) ?? "")) refuse(`remote provider '${q.provider}' sends it to ${unsigned.to}, which the app did not pin (remoteProvider callTargets)`);
       }