@circle-fin/app-kit 1.11.0 → 1.12.0

package/index.mjs

@@ -38,46 +38,9 @@ import { PublicKey } from '@solana/web3.js';
 import 'bn.js';
 import '@coral-xyz/anchor';
 import '@noble/curves/ed25519';
+import { decodeFunctionData } from 'viem';
 import { keccak256 } from '@ethersproject/keccak256';
 
-/**
- * Creates a AppKit context.
- *
- * This function constructs a context object, initializes the actions registry
- * used for event handlers, and merges in any custom implementations provided
- * via params.
- *
- * @param params - Optional custom implementations to override defaults
- * @returns A AppKitContext
- *
- * @example
- * ```typescript
- * // Create context with all defaults
- * const defaultContext = createContext()
- *
- * // Create context with custom fee calculation
- * const customContext = createContext({
- *   getFee: async (type, params) => {
- *     if (type === 'bridge') {
- *       // Custom bridge fee logic
- *       return await calculateBridgeFee(params)
- *     }
- *     // Use default for other types
- *     return defaultFeeCalculation(type, params)
- *   }
- * })
- * ```
- */ const createContext = (params = {})=>{
-    return {
-        ...params,
-        actions: {
-            bridge: {},
-            earn: {},
-            ...params.actions
-        }
-    };
-};
-
 // Import global type declarations
 /**
  * Check whether the current runtime is Node.js.
@@ -4123,6 +4086,8 @@ function getOptionalString(value) {
     Blockchain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
     Blockchain["XDC"] = "XDC";
     Blockchain["XDC_Apothem"] = "XDC_Apothem";
+    Blockchain["X_Layer"] = "X_Layer";
+    Blockchain["X_Layer_Testnet"] = "X_Layer_Testnet";
     Blockchain["ZKSync_Era"] = "ZKSync_Era";
     Blockchain["ZKSync_Sepolia"] = "ZKSync_Sepolia";
 })(Blockchain || (Blockchain = {}));
@@ -4176,6 +4141,7 @@ var BridgeChain;
     BridgeChain["Unichain"] = "Unichain";
     BridgeChain["World_Chain"] = "World_Chain";
     BridgeChain["XDC"] = "XDC";
+    BridgeChain["X_Layer"] = "X_Layer";
     // Testnet chains with CCTPv2 support
     BridgeChain["Arc_Testnet"] = "Arc_Testnet";
     BridgeChain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
@@ -4201,6 +4167,7 @@ var BridgeChain;
     BridgeChain["Unichain_Sepolia"] = "Unichain_Sepolia";
     BridgeChain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
     BridgeChain["XDC_Apothem"] = "XDC_Apothem";
+    BridgeChain["X_Layer_Testnet"] = "X_Layer_Testnet";
 })(BridgeChain || (BridgeChain = {}));
 var UnifiedBalanceChain;
 (function(UnifiedBalanceChain) {
@@ -6759,7 +6726,8 @@ var EarnChain;
     isTestnet: true,
     explorerUrl: 'https://amoy.polygonscan.com/tx/{hash}',
     rpcEndpoints: [
-        'https://rpc-amoy.polygon.technology'
+        'https://polygon-amoy-bor-rpc.publicnode.com',
+        'https://polygon-amoy.drpc.org'
     ],
     eurcAddress: null,
     usdcAddress: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
@@ -7624,6 +7592,104 @@ var EarnChain;
     }
 });
 
+/**
+ * X Layer Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the X Layer blockchain.
+ * X Layer is an EVM-compatible OP Stack Layer-2 blockchain built by OKX,
+ * using OKB as its native gas token. (Migrated from Polygon zkEVM/CDK to the
+ * OP Stack on 2025-10-27; older docs describing it as zkEVM are obsolete.)
+ */ const XLayer = defineChain({
+    type: 'evm',
+    chain: Blockchain.X_Layer,
+    name: 'X Layer',
+    title: 'X Layer Mainnet',
+    nativeCurrency: {
+        name: 'OKB',
+        symbol: 'OKB',
+        decimals: 18
+    },
+    chainId: 196,
+    isTestnet: false,
+    explorerUrl: 'https://www.oklink.com/xlayer/tx/{hash}',
+    rpcEndpoints: [
+        'https://xlayerrpc.okx.com'
+    ],
+    eurcAddress: null,
+    usdcAddress: '0xB6CEceAB302E2E4948951eE7843FC24E92933061',
+    usdtAddress: null,
+    cctp: {
+        domain: 37,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 65,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET
+    }
+});
+
+/**
+ * X Layer Testnet chain definition
+ * @remarks
+ * This represents the official test network for the X Layer blockchain.
+ * X Layer is an EVM-compatible OP Stack Layer-2 blockchain built by OKX,
+ * using OKB as its native gas token. (Migrated from Polygon zkEVM/CDK to the
+ * OP Stack on 2025-10-27; older docs describing it as zkEVM are obsolete.)
+ */ const XLayerTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.X_Layer_Testnet,
+    name: 'X Layer Testnet',
+    title: 'X Layer Testnet',
+    nativeCurrency: {
+        name: 'OKB',
+        symbol: 'OKB',
+        decimals: 18
+    },
+    chainId: 1952,
+    isTestnet: true,
+    // Deliberately not oklink.com (used for mainnet): viem's bundled OKLink
+    // testnet URL targets the deprecated pre-rebrand chain ID 195, not this
+    // chain's ID (1952). Verified against the internal chain-expansion-scripts
+    // config (`v2config.sandbox.yml`) — do not "normalize" this to match mainnet.
+    explorerUrl: 'https://web3.okx.com/explorer/x-layer-testnet/tx/{hash}',
+    rpcEndpoints: [
+        'https://testrpc.xlayer.tech'
+    ],
+    eurcAddress: null,
+    usdcAddress: '0xDec90b78111Ba2fc6FC6d84d8B9ec159A2d4b9B3',
+    usdtAddress: null,
+    cctp: {
+        domain: 37,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 65,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET
+    }
+});
+
 /**
  * ZKSync Era Mainnet chain definition
  * @remarks
@@ -7743,6 +7809,8 @@ var Chains = /*#__PURE__*/Object.freeze({
   WorldChainSepolia: WorldChainSepolia,
   XDC: XDC,
   XDCApothem: XDCApothem,
+  XLayer: XLayer,
+  XLayerTestnet: XLayerTestnet,
   ZKSyncEra: ZKSyncEra,
   ZKSyncEraSepolia: ZKSyncEraSepolia
 });
@@ -10106,6 +10174,7 @@ function parseOrThrow(value, schema, context) {
         [Blockchain.Unichain]: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
         [Blockchain.World_Chain]: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
         [Blockchain.XDC]: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
+        [Blockchain.X_Layer]: '0xB6CEceAB302E2E4948951eE7843FC24E92933061',
         [Blockchain.ZKSync_Era]: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
         // =========================================================================
         // Testnets (alphabetically sorted)
@@ -10140,6 +10209,7 @@ function parseOrThrow(value, schema, context) {
         [Blockchain.Unichain_Sepolia]: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
         [Blockchain.World_Chain_Sepolia]: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
         [Blockchain.XDC_Apothem]: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
+        [Blockchain.X_Layer_Testnet]: '0xDec90b78111Ba2fc6FC6d84d8B9ec159A2d4b9B3',
         [Blockchain.ZKSync_Sepolia]: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853'
     }
 };
@@ -11089,6 +11159,52 @@ function parseOrThrow(value, schema, context) {
     return explorerUrl;
 }
 
+/**
+ * Assert that a value has type `never` (exhaustive switch helper).
+ *
+ * @remarks
+ * Use in the `default` branch of a switch over a discriminated union.
+ * If all union members are handled, the default is unreachable and TypeScript
+ * narrows the parameter to `never`. If a member is missed, the compiler errors.
+ *
+ * @param _x - The value (typed as `never` when switch is exhaustive).
+ * @returns Never returns; always throws.
+ * @throws Error when the switch is not exhaustive.
+ *
+ * @example
+ * ```typescript
+ * type Foo = { type: 'a'; x: number } | { type: 'b'; y: string }
+ *
+ * function handle(foo: Foo): string {
+ *   switch (foo.type) {
+ *     case 'a': return String(foo.x)
+ *     case 'b': return foo.y
+ *     default: return assertNever(foo)
+ *   }
+ * }
+ * ```
+ */ function assertNever$2(x) {
+    // Plain `String(x)` collapses non-primitive union members (objects, arrays)
+    // to `'[object Object]'`, which is useless when triaging which discriminant
+    // was missed. Attempt `JSON.stringify` first so the thrown message preserves
+    // the offending shape. Fall back to a minimal `typeof`-based label if
+    // serialization fails (`BigInt` member, circular references, host objects).
+    //
+    // `x` is statically typed as `never` (the whole point of this helper), but
+    // at runtime callers may still pass an unexpected value when the switch is
+    // not actually exhaustive — that's exactly the bug we want to surface. Cast
+    // through `unknown` so the runtime defence is not stripped by the compiler.
+    const value = x;
+    let stringified;
+    try {
+        const json = JSON.stringify(value);
+        stringified = typeof json === 'string' ? json : `<${typeof value}>`;
+    } catch  {
+        stringified = `<unstringifiable ${typeof value}>`;
+    }
+    throw new Error(`Unhandled switch case: ${stringified}`);
+}
+
 /**
  * CCTP forwarding magic bytes prefix.
  *
@@ -11749,7 +11865,7 @@ function resolveOptions(options) {
 }
 
 var name$4 = "@circle-fin/bridge-kit";
-var version$5 = "1.12.2";
+var version$5 = "1.13.0";
 var pkg$5 = {
 	name: name$4,
 	version: version$5};
@@ -11786,13 +11902,21 @@ const assertCustomFeePolicySymbol$2 = Symbol('assertCustomFeePolicy');
     computeFee: z.function().returns(z.string().or(z.promise(z.string()))).optional(),
     calculateFee: z.function().returns(z.string().or(z.promise(z.string()))).optional(),
     resolveFeeRecipientAddress: z.function().returns(z.string().or(z.promise(z.string())))
-}).strict().refine((data)=>{
+}).strict().superRefine((data, ctx)=>{
     const hasComputeFee = data.computeFee !== undefined;
     const hasCalculateFee = data.calculateFee !== undefined;
-    // XOR: exactly one must be provided
-    return hasComputeFee !== hasCalculateFee;
-}, {
-    message: 'Provide either computeFee or calculateFee, not both. Use computeFee (recommended) for human-readable amounts.'
+    if (hasComputeFee && hasCalculateFee) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Provide either computeFee or calculateFee, not both. Use computeFee (recommended) for human-readable amounts.'
+        });
+    }
+    if (!hasComputeFee && !hasCalculateFee) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Provide either computeFee or calculateFee. Use computeFee (recommended) for human-readable amounts.'
+        });
+    }
 });
 /**
  * Assert that the provided value conforms to {@link CustomFeePolicy}.
@@ -14592,14 +14716,32 @@ const CUSTOM_BURN_GAS_ESTIMATE_EVM = 201_525n // p99 and max are same here: 201_
 ;
 const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_839n) / 2 = 237_401n
 ;
-// Hard execution caps: observed max + ~30% buffer, used as gasLimit overrides on
-// chains whose eth_estimateGas under-reports (e.g. Cronos EIP-7623 calldata floor).
-// Kept separate from the fee-estimate averages above.
-const APPROVE_GAS_LIMIT_EVM = 100_000n // ERC-20 approve observed max ~46k
+// Gas FLOORS, not ceilings — kept separate from the fee-estimate averages
+// above. `executePreparedChainRequest` submits
+// max(estimate * buffer, floor), so a chain whose real cost exceeds the floor
+// is covered by its own estimate, and a chain whose estimator under-reports
+// (Cronos: returns 30_600 where the EIP-7623 calldata floor is 45_000) is
+// covered by the floor.
+//
+// Two distinct chain surcharges drive these numbers, both measured live:
+//   Sei  — ~+51_500 per NEWLY CREATED storage slot (73_595 vs vanilla 22_100);
+//          no flat per-tx surcharge (31_535, identical to Base).
+//   Edge — ~+53_200 flat on EVERY tx (84_751 vs Base 31_535); storage priced
+//          normally. Edge therefore fails warm as well as cold.
+// A floor must clear the worst COLD cost, since a slot that exists at estimate
+// time can be consumed before inclusion and cost a full step more on execution.
+// Each floor is therefore derived from the worst observed estimate *after* the
+// 1.25x buffer, plus headroom — sizing it below the buffered value would leave
+// the estimate governing and defeat the point of the floor.
+//
+// The `*_GAS_LIMIT_EVM` names are kept despite these being floors: they are
+// exported, so renaming to `*_GAS_FLOOR_EVM` would be a breaking change for
+// consumers. Read "LIMIT" here as "the limit we submit", never as a ceiling.
+const APPROVE_GAS_LIMIT_EVM = 150_000n // buffered worst cold 149_355 (Edge Testnet 119_484 x 1.25) + drift headroom
 ;
-const DEPOSIT_FOR_BURN_GAS_LIMIT_EVM = 300_000n // observed max 226_506 + ~30%
+const DEPOSIT_FOR_BURN_GAS_LIMIT_EVM = 500_000n // buffered worst 474_078 (Sei 379_263 x 1.25) + ~26k headroom
 ;
-const RECEIVE_MESSAGE_GAS_LIMIT_EVM = 400_000n // observed max 310_839 + ~30%
+const RECEIVE_MESSAGE_GAS_LIMIT_EVM = 400_000n // observed max 310_839; clears Cronos' calldata floor ~10x
 ;
 /**
  * The minimum finality threshold for CCTPv2 transfers.
@@ -16064,6 +16206,63 @@ function hasPendingState(analysis, result) {
     return waitForPendingTransaction(pendingStep, adapter, chain);
 }
 
+/**
+ * Multiplier applied to a successful gas estimate before it is submitted.
+ *
+ * Estimates are exact, not padded: Sei returns 109_739 for an approve that
+ * consumes 107_717 (1.9% headroom). Chains that price storage in large steps
+ * can exceed the estimate if state changes between estimation and inclusion,
+ * so the estimate is padded before use.
+ *
+ * @remarks
+ * This buffer alone does NOT cover Sei's ~51_500 per-new-slot step at approve
+ * scale (25% of ~110_000 is only ~27_500). For approve, the FLOOR is what
+ * covers a slot that exists at estimation time and is consumed before
+ * inclusion — so do not lower `APPROVE_GAS_LIMIT_EVM` on the reasoning that
+ * the estimate covers it. For burn the buffer does cover a step (25% of
+ * ~300_000 exceeds 51_500).
+ */ const GAS_ESTIMATE_BUFFER_PERCENT = 125n;
+/**
+ * Resolve the gas limit for an EVM request as `max(estimate * buffer, floor)`.
+ *
+ * Estimates first so chains whose real cost exceeds the floor are covered by
+ * their own measurement, and falls back to the floor whenever estimation is
+ * unavailable or under-reports. Estimation failure is never fatal here: before
+ * floors existed these requests were submitted with a pinned limit and no
+ * estimate at all, so degrading to the floor is never worse than the previous
+ * behaviour.
+ *
+ * @param request - The prepared EVM request to size a gas limit for
+ * @param gasFloor - The minimum gas limit to submit, in gas units
+ * @returns The gas limit to submit, in gas units
+ * @throws Never — estimation failures degrade to `gasFloor`
+ *
+ * @example
+ * ```typescript
+ * const gasLimit = await resolveGasLimit(request, 150_000)
+ * ```
+ */ const resolveGasLimit = async (request, gasFloor)=>{
+    try {
+        // Deliberately called without a `fallback`: both the viem and ethers
+        // adapters *return* the supplied fallback object when estimation reverts
+        // rather than throwing, which would set the estimate to the floor and then
+        // multiply it by the buffer below. Omitting it routes reverts through the
+        // catch, so a failed estimate degrades to exactly the floor.
+        const estimate = await request.estimate();
+        // The arithmetic stays inside the try on purpose. `EstimatedGas.gas` is
+        // typed `bigint`, but adapters are a public extension point and may be
+        // implemented in plain JS, so a non-bigint `gas` would throw here
+        // ("Cannot mix BigInt and other types"). Guarding it keeps the documented
+        // contract — estimation never aborts a step, it degrades to the floor.
+        const buffered = estimate.gas * GAS_ESTIMATE_BUFFER_PERCENT / 100n;
+        // Convert before comparing: Math.max throws on BigInt operands, and gas
+        // units are far below Number.MAX_SAFE_INTEGER so the narrowing is lossless.
+        return Math.max(Number(buffered), gasFloor);
+    } catch  {
+        // Estimation is best-effort; the floor is the known-safe value.
+        return gasFloor;
+    }
+};
 /**
  * Executes a prepared chain request and returns the result as a bridge step.
  *
@@ -16077,8 +16276,8 @@ function hasPendingState(analysis, result) {
  *   - `adapter`: The adapter that will execute the transaction
  *   - `confirmations`: The number of confirmations to wait for (defaults to 1)
  *   - `timeout`: The timeout for the request in milliseconds
- *   - `gasLimit`: Optional explicit gas limit (number) forwarded to EVM execute,
- *     bypassing `eth_estimateGas`; ignored for non-EVM requests
+ *   - `gasFloor`: Optional minimum gas limit (number); the request is submitted
+ *     with `max(estimate * 1.25, gasFloor)`. Ignored for non-EVM requests
  * @returns The bridge step with the transaction details and explorer URL
  * @throws If the transaction execution fails
  *
@@ -16093,7 +16292,7 @@ function hasPendingState(analysis, result) {
  * })
  * console.log('Transaction hash:', step.txHash)
  * ```
- */ async function executePreparedChainRequest({ name, request, adapter, chain, confirmations = 1, timeout, gasLimit }) {
+ */ async function executePreparedChainRequest({ name, request, adapter, chain, confirmations = 1, timeout, gasFloor }) {
     const step = {
         name,
         state: 'pending'
@@ -16106,8 +16305,8 @@ function hasPendingState(analysis, result) {
             step.state = 'noop';
             return step;
         }
-        const txHash = request.type === 'evm' && gasLimit !== undefined ? await request.execute({
-            gasLimit
+        const txHash = request.type === 'evm' && gasFloor !== undefined ? await request.execute({
+            gasLimit: await resolveGasLimit(request, gasFloor)
         }) : await request.execute();
         step.txHash = txHash;
         const retryOptions = {
@@ -16181,7 +16380,7 @@ function hasPendingState(analysis, result) {
         adapter: params.source.adapter,
         chain: params.source.chain,
         request: await provider.approve(params.source, approvalAmount),
-        gasLimit: Number(APPROVE_GAS_LIMIT_EVM)
+        gasFloor: Number(APPROVE_GAS_LIMIT_EVM)
     });
 }
 
@@ -16209,7 +16408,7 @@ function hasPendingState(analysis, result) {
         adapter: params.source.adapter,
         chain: params.source.chain,
         request: await provider.burn(params),
-        gasLimit: Number(DEPOSIT_FOR_BURN_GAS_LIMIT_EVM)
+        gasFloor: Number(DEPOSIT_FOR_BURN_GAS_LIMIT_EVM)
     });
 }
 
@@ -16303,10 +16502,9 @@ function hasPendingState(analysis, result) {
         request: mintRequest,
         // Some chains (e.g. Cronos) enforce an EIP-7623 calldata gas floor that
         // eth_estimateGas does not account for, returning a below-floor value
-        // without reverting. Pinning to a value above the observed execution max
-        // (310_839) bypasses re-estimation and guarantees we clear both the floor
-        // and the actual execution cost.
-        gasLimit: Number(RECEIVE_MESSAGE_GAS_LIMIT_EVM)
+        // without reverting. The floor covers those; chains that cost more than the
+        // floor are covered by their own estimate.
+        gasFloor: Number(RECEIVE_MESSAGE_GAS_LIMIT_EVM)
     });
     // Add forwarded: false for non-relayer mints
     return {
@@ -16829,7 +17027,7 @@ const mockAttestationMessage = {
     return step;
 }
 
-var version$4 = "1.10.1";
+var version$4 = "1.10.2";
 var pkg$4 = {
 	version: version$4};
 
@@ -19375,75 +19573,8 @@ function assertCCTPV2Config(config) {
 // Auto-register this kit for user agent tracking
 registerKit(`${pkg$5.name}/${pkg$5.version}`);
 
-/**
- * Create a BridgeKit instance with optional developer fee configuration.
- *
- * This utility creates a BridgeKit instance that optionally includes developer
- * fee configuration based on the provided AppKit context. If the context
- * provides both `getFee` and `getFeeRecipient` methods, they will be configured
- * as developer fees in the BridgeKit instance using the `setCustomFeePolicy` method.
- *
- * The fee integration transforms string-based fees from the context into the
- * format expected by BridgeKit, enabling seamless fee calculation across both kits.
- *
- * @param context - The AppKit context containing optional fee methods
- * @returns A configured BridgeKit instance with or without developer fees
- *
- * @example
- * ```typescript
- * import { createBridgeKit } from '@circle-fin/app-kit/utils'
- * import { createContext } from '@circle-fin/app-kit/context'
- *
- * // Create context with fee methods
- * const context = createContext({
- *   getFee: async (type, params) => '1000000', // 1 USDC in micro-units
- *   getFeeRecipient: async (type, info) => '0x742d35Cc4634C0532925a3b8D1d7'
- * })
- *
- * // Create BridgeKit with developer fees
- * const bridgeKit = createBridgeKit(context)
- * ```
- *
- * @example
- * ```typescript
- * import { createBridgeKit } from '@circle-fin/app-kit/utils'
- * import { createContext } from '@circle-fin/app-kit/context'
- *
- * // Create context without fee methods
- * const context = createContext()
- *
- * // Create standard BridgeKit instance
- * const bridgeKit = createBridgeKit(context)
- * ```
- */ const createBridgeKit = (context)=>{
-    const getFee = context.getFee?.bind(context);
-    const getFeeRecipient = context.getFeeRecipient?.bind(context);
-    const hasBoth = typeof getFee === 'function' && typeof getFeeRecipient === 'function';
-    const kit = new BridgeKit({
-        ...context.disableErrorReporting != null && {
-            disableErrorReporting: context.disableErrorReporting
-        },
-        ...context.headers != null && {
-            headers: context.headers
-        }
-    });
-    if (hasBoth) {
-        kit.setCustomFeePolicy({
-            calculateFee: async (params)=>{
-                const feeStr = await getFee('bridge', params);
-                return feeStr;
-            },
-            resolveFeeRecipientAddress: async (chain, params)=>await getFeeRecipient('bridge', {
-                    chain,
-                    params: params || {}
-                })
-        });
-    }
-    return kit;
-};
-
 var name$3 = "@circle-fin/swap-kit";
-var version$3 = "1.5.0";
+var version$3 = "1.5.1";
 var pkg$3 = {
 	name: name$3,
 	version: version$3};
@@ -20859,6 +20990,138 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     return pollApiGet(url, isGetTokenRatesResponse, effectiveConfig);
 };
 
+/**
+ * IAdapter contract ABI.
+ *
+ * Shared ABI for the on-chain Adapter contract used by multiple kits
+ * (swap, earn) for executing signed instruction sets. The `execute()`
+ * function accepts EIP-712 signed execution parameters, token inputs,
+ * and a signature, then executes the corresponding on-chain
+ * instructions.
+ */ const adapterContractAbi = [
+    {
+        type: 'function',
+        name: 'execute',
+        inputs: [
+            {
+                name: 'params',
+                type: 'tuple',
+                internalType: 'struct IAdapter.ExecutionParams',
+                components: [
+                    {
+                        name: 'instructions',
+                        type: 'tuple[]',
+                        internalType: 'struct IAdapter.Instruction[]',
+                        components: [
+                            {
+                                name: 'target',
+                                type: 'address',
+                                internalType: 'address'
+                            },
+                            {
+                                name: 'data',
+                                type: 'bytes',
+                                internalType: 'bytes'
+                            },
+                            {
+                                name: 'value',
+                                type: 'uint256',
+                                internalType: 'uint256'
+                            },
+                            {
+                                name: 'tokenIn',
+                                type: 'address',
+                                internalType: 'address'
+                            },
+                            {
+                                name: 'amountToApprove',
+                                type: 'uint256',
+                                internalType: 'uint256'
+                            },
+                            {
+                                name: 'tokenOut',
+                                type: 'address',
+                                internalType: 'address'
+                            },
+                            {
+                                name: 'minTokenOut',
+                                type: 'uint256',
+                                internalType: 'uint256'
+                            }
+                        ]
+                    },
+                    {
+                        name: 'tokens',
+                        type: 'tuple[]',
+                        internalType: 'struct IAdapter.TokenRecipient[]',
+                        components: [
+                            {
+                                name: 'token',
+                                type: 'address',
+                                internalType: 'address'
+                            },
+                            {
+                                name: 'beneficiary',
+                                type: 'address',
+                                internalType: 'address'
+                            }
+                        ]
+                    },
+                    {
+                        name: 'execId',
+                        type: 'uint256',
+                        internalType: 'uint256'
+                    },
+                    {
+                        name: 'deadline',
+                        type: 'uint256',
+                        internalType: 'uint256'
+                    },
+                    {
+                        name: 'metadata',
+                        type: 'bytes',
+                        internalType: 'bytes'
+                    }
+                ]
+            },
+            {
+                name: 'tokenInputs',
+                type: 'tuple[]',
+                internalType: 'struct IAdapter.TokenInput[]',
+                components: [
+                    {
+                        name: 'permitType',
+                        type: 'uint8',
+                        internalType: 'enum IAdapter.PermitType'
+                    },
+                    {
+                        name: 'token',
+                        type: 'address',
+                        internalType: 'address'
+                    },
+                    {
+                        name: 'amount',
+                        type: 'uint256',
+                        internalType: 'uint256'
+                    },
+                    {
+                        name: 'permitCalldata',
+                        type: 'bytes',
+                        internalType: 'bytes'
+                    }
+                ]
+            },
+            {
+                name: 'signature',
+                type: 'bytes',
+                internalType: 'bytes'
+            }
+        ],
+        outputs: [],
+        stateMutability: 'payable'
+    }
+];
+
 /**
  * USDC ABI
  *
@@ -22094,6 +22357,179 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     }
 ];
 
+/**
+ * Minimal ERC-4626 tokenized-vault ABI.
+ *
+ * Covers only the mutating methods EarnKit bundles as inner instructions inside
+ * an Adapter `execute()` call: `deposit`, `withdraw`, and `redeem`. It exists so
+ * clients can decode the inner instruction calldata into a human-readable
+ * summary of what a signer is authorizing (asset amount, receiver, owner)
+ * rather than showing opaque bytes. The 4-byte selectors match the calldata the
+ * earn service signs (`deposit(uint256,address)` = `0x6e553f65`,
+ * `withdraw(uint256,address,address)` = `0xb460af94`,
+ * `redeem(uint256,address,address)` = `0xba087652`).
+ */ const erc4626VaultAbi = [
+    {
+        type: 'function',
+        name: 'deposit',
+        stateMutability: 'nonpayable',
+        inputs: [
+            {
+                name: 'assets',
+                type: 'uint256',
+                internalType: 'uint256'
+            },
+            {
+                name: 'receiver',
+                type: 'address',
+                internalType: 'address'
+            }
+        ],
+        outputs: [
+            {
+                name: 'shares',
+                type: 'uint256',
+                internalType: 'uint256'
+            }
+        ]
+    },
+    {
+        type: 'function',
+        name: 'withdraw',
+        stateMutability: 'nonpayable',
+        inputs: [
+            {
+                name: 'assets',
+                type: 'uint256',
+                internalType: 'uint256'
+            },
+            {
+                name: 'receiver',
+                type: 'address',
+                internalType: 'address'
+            },
+            {
+                name: 'owner',
+                type: 'address',
+                internalType: 'address'
+            }
+        ],
+        outputs: [
+            {
+                name: 'shares',
+                type: 'uint256',
+                internalType: 'uint256'
+            }
+        ]
+    },
+    {
+        type: 'function',
+        name: 'redeem',
+        stateMutability: 'nonpayable',
+        inputs: [
+            {
+                name: 'shares',
+                type: 'uint256',
+                internalType: 'uint256'
+            },
+            {
+                name: 'receiver',
+                type: 'address',
+                internalType: 'address'
+            },
+            {
+                name: 'owner',
+                type: 'address',
+                internalType: 'address'
+            }
+        ],
+        outputs: [
+            {
+                name: 'assets',
+                type: 'uint256',
+                internalType: 'uint256'
+            }
+        ]
+    }
+];
+
+/**
+ * Minimal FeeTaker ABI.
+ *
+ * The earn service appends a `takeFeeERC20` instruction to withdraw bundles
+ * when Circle charges a withdrawal fee. This ABI decodes that inner instruction
+ * so the fee (token, beneficiary, amount) is visible in the signing summary
+ * instead of appearing as opaque calldata alongside the redeem/withdraw call.
+ */ const feeTakerAbi = [
+    {
+        type: 'function',
+        name: 'takeFeeERC20',
+        stateMutability: 'nonpayable',
+        inputs: [
+            {
+                name: 'token',
+                type: 'address',
+                internalType: 'address'
+            },
+            {
+                name: 'beneficiary',
+                type: 'address',
+                internalType: 'address'
+            },
+            {
+                name: 'fee',
+                type: 'uint256',
+                internalType: 'uint256'
+            },
+            {
+                name: 'kitType',
+                type: 'bytes8',
+                internalType: 'bytes8'
+            }
+        ],
+        outputs: []
+    }
+];
+
+/**
+ * Minimal Merkl Distributor ABI.
+ *
+ * EarnKit claim-rewards bundles a single `claim` instruction targeting the
+ * Merkl Distributor, batching one entry per reward token. This ABI decodes that
+ * inner instruction so the claimed tokens and amounts are visible in the signing
+ * summary. `claim` uses dynamic array arguments, which is why a real ABI decoder
+ * (rather than fixed-word slicing) is required for the reward instruction.
+ */ const merklDistributorAbi = [
+    {
+        type: 'function',
+        name: 'claim',
+        stateMutability: 'nonpayable',
+        inputs: [
+            {
+                name: 'users',
+                type: 'address[]',
+                internalType: 'address[]'
+            },
+            {
+                name: 'tokens',
+                type: 'address[]',
+                internalType: 'address[]'
+            },
+            {
+                name: 'amounts',
+                type: 'uint256[]',
+                internalType: 'uint256[]'
+            },
+            {
+                name: 'proofs',
+                type: 'bytes32[][]',
+                internalType: 'bytes32[][]'
+            }
+        ],
+        outputs: []
+    }
+];
+
 /**
  * Zod schema for validating EVM adapter capabilities.
  *
@@ -23602,72 +24038,55 @@ function evmSigningData(burnIntent) {
  * `0xef0100` followed by the 20-byte delegate address (23 bytes total).
  * The underlying secp256k1 key still produces `ecrecover`-verifiable
  * signatures, so for Gateway's purposes a 7702-delegated address is
- * an EOA, not an SCA.
+ * an EOA, not a contract signer.
  *
  * Spec: https://eips.ethereum.org/EIPS/eip-7702
  */ const EIP_7702_DELEGATION_PREFIX = '0xef0100';
 /**
- * Assert that `address` on `chain` can sign Gateway burn intents.
+ * Determine whether `address` on `chain` signs as a contract (ERC-1271)
+ * rather than as an EOA.
  *
- * Gateway verifies burn-intent signatures with plain `ecrecover` (see
- * `evm-gateway-contracts/src/lib/EIP712Domain.sol`). Smart-contract
- * accounts (SCAs) produce signatures over wrapped hashes (ERC-1271 /
- * ERC-6492 / ERC-6900 replay-safe hashes) that Gateway cannot verify.
- * Additionally, the Circle Wallets backend rejects SCA typed-data signing
- * against Gateway's chainId-less domain with an opaque
- * `invalid integer value <nil>/<nil> for type uint256` error.
+ * Gateway validates burn-intent signatures two ways: a static `ecrecover`
+ * check for EOAs, and — for requests that carry `contractSigner: true` —
+ * an offchain `isValidSignature` simulation against the signing contract
+ * (ERC-1271). Gateway does not infer which one to use, so the caller must
+ * declare it. This detects the contract case from on-chain bytecode.
  *
- * EIP-7702-delegated EOAs are exempt: they expose non-empty bytecode
- * (`0xef0100<delegate>`) but the underlying secp256k1 key still produces
- * `ecrecover`-verifiable signatures, so Gateway accepts them.
+ * EIP-7702-delegated EOAs are treated as EOAs: they expose non-empty
+ * bytecode (`0xef0100<delegate>`) but the underlying secp256k1 key still
+ * produces `ecrecover`-verifiable signatures, so the cheaper EOA path
+ * stays correct for them.
  *
- * When the signer is a true SCA, raises an `INPUT_UNSUPPORTED_ACTION`
- * error directing the caller to register an EOA delegate against the
- * SCA and then submit the spend with the delegate EOA as the signer
- * and the SCA as the source account. See the unified-balance / Gateway
- * docs for the exact API.
- *
- * If bytecode cannot be read (RPC failure, etc.) the pre-check is
- * skipped and downstream signing surfaces its own error — a warning is
- * logged so the skip is diagnosable.
+ * If bytecode cannot be read (RPC failure, etc.) the address is reported
+ * as an EOA and a warning is logged so the fallback is diagnosable. A
+ * genuine contract signer misreported this way is rejected by Gateway with
+ * an invalid-signature error rather than silently mis-attested.
  *
  * @param adapter - Anything exposing {@link EvmAdapterLike.readBytecode}.
- * @param address - Signer address to validate.
+ * @param address - Signer address to classify.
  * @param chain - EVM chain where the signer lives.
- * @throws {KitError} INPUT_UNSUPPORTED_ACTION when `address` is an SCA.
+ * @returns `true` when the signer is a contract account and the transfer
+ *   request must set `contractSigner: true`; `false` otherwise.
  *
  * @example
  * ```typescript
- * import { assertSignerIsEoa } from '@core/adapter-evm'
+ * import { isContractSigner } from '@core/adapter-evm'
  * import { Ethereum } from '@core/chains'
  *
- * await assertSignerIsEoa(adapter, '0xabc...', Ethereum)
+ * const useErc1271 = await isContractSigner(adapter, '0xabc...', Ethereum)
  * ```
- */ async function assertSignerIsEoa(adapter, address, chain) {
+ */ async function isContractSigner(adapter, address, chain) {
     let code;
     try {
         code = await adapter.readBytecode(address, chain);
     } catch (err) {
-        console.warn(`[gateway] assertSignerIsEoa skipped (readBytecode failed for ` + `${address} on ${chain.name}): ` + (err instanceof Error ? err.message : String(err)));
-        return;
+        console.warn(`[gateway] isContractSigner defaulting to EOA (readBytecode failed ` + `for ${address} on ${chain.name}): ` + (err instanceof Error ? err.message : String(err)));
+        return false;
     }
     if (code === undefined || code === '0x' || code.toLowerCase().startsWith(EIP_7702_DELEGATION_PREFIX)) {
-        return;
+        return false;
     }
-    throw new KitError({
-        ...InputError.UNSUPPORTED_ACTION,
-        recoverability: 'FATAL',
-        message: `Gateway burn-intent signing requires an EOA signer (Gateway ` + `verifies signatures with ecrecover and does not support ERC-1271). ` + `The signer ${address} on ${chain.name} has on-chain bytecode, ` + `indicating it is a smart-contract account (SCA). Register an EOA ` + `delegate against the SCA, then submit the spend with the delegate ` + `EOA as the signer and the SCA as the source account. See DEVX-2774.`,
-        cause: {
-            trace: {
-                operation: 'signEvmIntentGroup.assertSignerIsEoa',
-                address,
-                chain: chain.name,
-                bytecodeBytes: (code.length - 2) / 2,
-                bytecodePrefix: code.slice(0, 12)
-            }
-        }
-    });
+    return true;
 }
 
 /**
@@ -23694,78 +24113,177 @@ function evmSigningData(burnIntent) {
     return typeof value === 'object' && value !== null && 'readBytecode' in value && typeof value.readBytecode === 'function';
 }
 
+function resolveIntentChain(group, intent) {
+    const sourceDomain = intent.spec.sourceDomain;
+    const chain = group.chainsByDomain.get(sourceDomain);
+    if (chain !== undefined) return chain;
+    throw createValidationFailedError$1('intent.spec.sourceDomain', sourceDomain, `No source chain found for Gateway domain ${String(sourceDomain)}`);
+}
+function normalizeSignatureResult(result) {
+    if (typeof result === 'string') {
+        return {
+            signature: result,
+            contractSigner: false
+        };
+    }
+    if (typeof result === 'object' && result !== null && 'signature' in result && typeof result.signature === 'string') {
+        return {
+            signature: result.signature,
+            contractSigner: 'contractSigner' in result && result.contractSigner === true
+        };
+    }
+    throw createValidationFailedError$1('signature', result, 'must be a signature string or an object containing a signature string');
+}
+function validateGroupIntents(intents) {
+    evmSigningData(intents);
+}
+function collectChainsByDomain(group) {
+    const chainsByDomain = new Map();
+    for (const intent of group.intents){
+        chainsByDomain.set(intent.spec.sourceDomain, resolveIntentChain(group, intent));
+    }
+    return chainsByDomain;
+}
+async function classifySignerTypes(group, chainsByDomain) {
+    const { adapter, address } = group;
+    // Duck-typed on readBytecode rather than `instanceof EvmAdapter` because
+    // each consumer package bundles its own copy of the base class and the
+    // `instanceof` identity check fails across package boundaries.
+    // Empty strings are rejected to avoid calling eth_getCode('') on the RPC.
+    const hasResolvedSigner = typeof address === 'string' && address.length > 0;
+    const signerTypes = await Promise.all([
+        ...chainsByDomain
+    ].map(async ([sourceDomain, sourceChain])=>{
+        const contractSigner = hasResolvedSigner && sourceChain.type === 'evm' && isEvmAdapterLike(adapter) ? await isContractSigner(adapter, address, sourceChain) : false;
+        return [
+            sourceDomain,
+            contractSigner
+        ];
+    }));
+    return new Map(signerTypes);
+}
+function createSigningUnits(group, signerTypeByDomain) {
+    const contractUnitsByDomain = new Map();
+    let eoaUnit;
+    for (const [index, intent] of group.intents.entries()){
+        const sourceDomain = intent.spec.sourceDomain;
+        const contractSigner = signerTypeByDomain.get(sourceDomain) ?? false;
+        if (contractSigner) {
+            const existingUnit = contractUnitsByDomain.get(sourceDomain);
+            if (existingUnit === undefined) {
+                contractUnitsByDomain.set(sourceDomain, {
+                    intents: [
+                        intent
+                    ],
+                    chain: resolveIntentChain(group, intent),
+                    contractSigner: true,
+                    firstIntentIndex: index
+                });
+            } else {
+                existingUnit.intents.push(intent);
+            }
+        } else {
+            eoaUnit ??= {
+                intents: [],
+                chain: resolveIntentChain(group, intent),
+                contractSigner: false,
+                firstIntentIndex: index
+            };
+            eoaUnit.intents.push(intent);
+        }
+    }
+    const signingUnits = [
+        ...contractUnitsByDomain.values()
+    ];
+    if (eoaUnit !== undefined) signingUnits.push(eoaUnit);
+    signingUnits.sort((a, b)=>a.firstIntentIndex - b.firstIntentIndex);
+    return signingUnits;
+}
+async function signUnit(group, unit) {
+    const { adapter, address } = group;
+    const firstIntent = unit.intents[0];
+    const typedData = unit.intents.length === 1 && firstIntent !== undefined ? evmSigningData(firstIntent) : evmSigningData(unit.intents);
+    const operationContext = address === undefined ? {
+        chain: unit.chain
+    } : {
+        chain: unit.chain,
+        address
+    };
+    const signRequest = await adapter.prepareAction('gateway.v1.signBurnIntents', {
+        typedData,
+        chain: unit.chain
+    }, operationContext);
+    const result = normalizeSignatureResult(await signRequest.execute());
+    return {
+        intents: unit.intents,
+        signature: result.signature,
+        contractSigner: result.contractSigner || unit.contractSigner
+    };
+}
+async function signUnits(group, signingUnits) {
+    const signedSets = [];
+    // Keep wallet prompts deterministic. Multiple adapter groups can still sign
+    // in parallel, but one signer is asked for its chain-bound signatures in
+    // source-intent order.
+    for (const unit of signingUnits){
+        signedSets.push(await signUnit(group, unit));
+    }
+    return signedSets;
+}
 /**
- * Sign an EVM adapter group: batches all intents and produces a single
- * EIP-712 ECDSA signature.
+ * Sign an EVM adapter group.
  *
- * For a single-intent group, `primaryType` is `'BurnIntent'`.
- * For multi-intent groups, `primaryType` is `'BurnIntentSet'`.
+ * EOA intents remain batched into one EIP-712 `BurnIntentSet`. ERC-1271
+ * intents are grouped and signed per source chain because smart accounts
+ * commonly include `chainId` in their replay-safe signature hash.
+ * All returned entries can still be submitted together in one atomic Gateway
+ * transfer request.
  *
- * Before signing, asserts that the signer address is an EOA. Gateway
- * verifies burn-intent signatures with plain `ecrecover` (no ERC-1271
- * fallback), so signatures produced by smart-contract accounts (SCAs)
- * cannot be verified. When an SCA is detected, a clear error is raised
- * directing the caller to the delegate workflow (DEVX-2774).
+ * Before signing, classifies the signer as an EOA or a contract account.
+ * Gateway validates EOA signatures with `ecrecover` and contract-account
+ * signatures with ERC-1271, but it does not infer which one applies — the
+ * transfer request has to declare it. The returned `contractSigner` flag
+ * carries that decision through to `buildTransferRequestBody`.
  *
  * @param group - The adapter group containing the adapter, chain, and
  *   burn intents to sign.
- * @returns A signed set with the intents and the ECDSA signature.
+ * @returns Signed entries with their intents, signatures, and Gateway signer
+ *   validation mode.
+ * @throws KitError when an intent has no source-chain mapping or a signing
+ *   action returns an invalid signature shape.
  *
  * @example
  * ```typescript
  * import { signEvmIntentGroup } from '@core/adapter-evm'
  *
- * const signedSet = await signEvmIntentGroup({
+ * const signedSets = await signEvmIntentGroup({
  *   adapter: evmAdapter,
  *   chain: ethereumChain,
  *   intents: [burnIntent1, burnIntent2],
+ *   chainsByDomain: new Map([
+ *     [0, ethereumChain],
+ *     [6, baseChain],
+ *   ]),
  *   address: '0x...',
  * })
- * console.log(signedSet.signature)
+ * console.log(signedSets)
  * ```
  */ async function signEvmIntentGroup(group) {
-    const { adapter, intents: groupIntents, chain, address } = group;
-    const operationContext = address === undefined ? {
-        chain
-    } : {
-        chain,
-        address
-    };
-    // Gateway verifies burn-intent signatures with plain ecrecover. An SCA
-    // signer silently produces a signature over a wrapped hash that Gateway
-    // cannot verify, and Circle Wallets' KMS rejects the typed data up front
-    // with an opaque `<nil>/<nil>` error. Short-circuit with a clear message
-    // when we can detect bytecode at the signer address. See DEVX-2774.
-    //
-    // Duck-typed on readBytecode rather than `instanceof EvmAdapter` because
-    // each consumer package bundles its own copy of the base class and the
-    // `instanceof` identity check fails across package boundaries.
-    //
-    // Empty string is defended against because assertSignerIsEoa would
-    // otherwise call eth_getCode('') on the RPC.
-    const hasResolvedSigner = typeof address === 'string' && address.length > 0;
-    if (hasResolvedSigner && chain.type === 'evm' && isEvmAdapterLike(adapter)) {
-        await assertSignerIsEoa(adapter, address, chain);
-    }
-    const firstIntent = groupIntents[0];
-    const typedData = groupIntents.length === 1 && firstIntent ? evmSigningData(firstIntent) : evmSigningData(groupIntents);
-    const signRequest = await adapter.prepareAction('gateway.v1.signBurnIntents', {
-        typedData,
-        chain
-    }, operationContext);
-    const sig = await signRequest.execute();
-    return {
-        intents: groupIntents,
-        signature: sig
-    };
+    // Validate the collection before doing bytecode reads or asking a wallet
+    // to sign. evmSigningData owns the canonical BurnIntent validation.
+    validateGroupIntents(group.intents);
+    const chainsByDomain = collectChainsByDomain(group);
+    const signerTypeByDomain = await classifySignerTypes(group, chainsByDomain);
+    const signingUnits = createSigningUnits(group, signerTypeByDomain);
+    return await signUnits(group, signingUnits);
 }
 
 /**
  * Add an EVM intent into the batched EVM group map.
  *
  * On EVM, all intents for the same adapter are batched into a single
- * group so that they can be signed in one EIP-712 `BurnIntentSet`
- * operation.
+ * group. The signing step uses `chainsByDomain` to preserve EOA batching
+ * while signing ERC-1271 intents separately on their source chains.
  *
  * @param intent - The burn intent to group.
  * @param alloc - The allocation that resolved to this intent.
@@ -23782,6 +24300,7 @@ function evmSigningData(burnIntent) {
     const existing = evmGroups.get(alloc.adapter);
     if (existing) {
         existing.intents.push(intent);
+        existing.chainsByDomain.set(alloc.chain.gateway.domain, alloc.chain);
     } else {
         evmGroups.set(alloc.adapter, {
             adapter: alloc.adapter,
@@ -23789,6 +24308,12 @@ function evmSigningData(burnIntent) {
             intents: [
                 intent
             ],
+            chainsByDomain: new Map([
+                [
+                    alloc.chain.gateway.domain,
+                    alloc.chain
+                ]
+            ]),
             address: alloc.sourceSigner
         });
     }
@@ -31994,6 +32519,113 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
 // Auto-register this kit for user agent tracking
 registerKit(`${pkg$3.name}/${pkg$3.version}`);
 
+/**
+ * Creates a AppKit context.
+ *
+ * This function constructs a context object, initializes the actions registry
+ * used for event handlers, and merges in any custom implementations provided
+ * via params.
+ *
+ * @param params - Optional custom implementations to override defaults
+ * @returns A AppKitContext
+ *
+ * @example
+ * ```typescript
+ * // Create context with all defaults
+ * const defaultContext = createContext()
+ *
+ * // Create context with custom fee calculation
+ * const customContext = createContext({
+ *   getFee: async (type, params) => {
+ *     if (type === 'bridge') {
+ *       // Custom bridge fee logic
+ *       return await calculateBridgeFee(params)
+ *     }
+ *     // Use default for other types
+ *     return defaultFeeCalculation(type, params)
+ *   }
+ * })
+ * ```
+ */ const createContext = (params = {})=>{
+    return {
+        ...params,
+        actions: {
+            bridge: {},
+            earn: {},
+            ...params.actions
+        }
+    };
+};
+
+/**
+ * Create a BridgeKit instance with optional developer fee configuration.
+ *
+ * This utility creates a BridgeKit instance that optionally includes developer
+ * fee configuration based on the provided AppKit context. If the context
+ * provides both `getFee` and `getFeeRecipient` methods, they will be configured
+ * as developer fees in the BridgeKit instance using the `setCustomFeePolicy` method.
+ *
+ * The fee integration transforms string-based fees from the context into the
+ * format expected by BridgeKit, enabling seamless fee calculation across both kits.
+ *
+ * @param context - The AppKit context containing optional fee methods
+ * @returns A configured BridgeKit instance with or without developer fees
+ *
+ * @example
+ * ```typescript
+ * import { createBridgeKit } from '@circle-fin/app-kit/utils'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ *
+ * // Create context with fee methods
+ * const context = createContext({
+ *   getFee: async (type, params) => '1000000', // 1 USDC in micro-units
+ *   getFeeRecipient: async (type, info) => '0x742d35Cc4634C0532925a3b8D1d7'
+ * })
+ *
+ * // Create BridgeKit with developer fees
+ * const bridgeKit = createBridgeKit(context)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createBridgeKit } from '@circle-fin/app-kit/utils'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ *
+ * // Create context without fee methods
+ * const context = createContext()
+ *
+ * // Create standard BridgeKit instance
+ * const bridgeKit = createBridgeKit(context)
+ * ```
+ */ const createBridgeKit = (context)=>{
+    const getFee = context.getFee?.bind(context);
+    const getFeeRecipient = context.getFeeRecipient?.bind(context);
+    const hasBoth = typeof getFee === 'function' && typeof getFeeRecipient === 'function';
+    const kit = new BridgeKit({
+        ...context.disableErrorReporting != null && {
+            disableErrorReporting: context.disableErrorReporting
+        },
+        ...context.headers != null && {
+            headers: context.headers
+        }
+    });
+    if (context.customFeePolicy?.bridge != null) {
+        kit.setCustomFeePolicy(context.customFeePolicy.bridge);
+    } else if (hasBoth) {
+        kit.setCustomFeePolicy({
+            calculateFee: async (params)=>{
+                const feeStr = await getFee('bridge', params);
+                return feeStr;
+            },
+            resolveFeeRecipientAddress: async (chain, params)=>await getFeeRecipient('bridge', {
+                    chain,
+                    params: params || {}
+                })
+        });
+    }
+    return kit;
+};
+
 /**
  * Create a SwapKit instance with optional developer fee configuration.
  *
@@ -32032,7 +32664,9 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
             disableAnalytics: context.disableAnalytics
         }
     });
-    if (hasBoth) {
+    if (context.customFeePolicy?.swap != null) {
+        kit.setCustomFeePolicy(context.customFeePolicy.swap);
+    } else if (hasBoth) {
         kit.setCustomFeePolicy({
             computeFee: async (params)=>{
                 // Adapt provider-level params (with tokenIn/tokenOut)
@@ -32091,7 +32725,7 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
 };
 
 var name$2 = "@circle-fin/earn-kit";
-var version$2 = "1.4.0";
+var version$2 = "1.5.0";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -32734,6 +33368,683 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
     return approvedToken;
 }
 
+/**
+ * Combined ABI of every inner instruction EarnKit can bundle inside an Adapter
+ * `execute()` call. `decodeFunctionData` matches an instruction's calldata to
+ * one of these functions by its 4-byte selector.
+ */ const earnInstructionAbi = [
+    ...erc4626VaultAbi,
+    ...feeTakerAbi,
+    ...merklDistributorAbi
+];
+/**
+ * Extract and shallow-validate the `instructions` array from loosely-typed
+ * signed execution params.
+ *
+ * The earn service schema validates `tokenIn`/`amountToApprove` and passes the
+ * remaining instruction fields through untyped, so the params arrive as a plain
+ * record; each accessed field is narrowed at runtime.
+ */ function requireInstructions(executionParams) {
+    const instructions = executionParams['instructions'];
+    if (!Array.isArray(instructions)) {
+        throw decodeMismatchError('execution params are missing an instructions array', {
+            instructions
+        });
+    }
+    return instructions.map((instruction, index)=>{
+        if (typeof instruction !== 'object' || instruction === null) {
+            throw decodeMismatchError(`instructions[${index.toString()}] is not an object`, {
+                index
+            });
+        }
+        return instruction;
+    });
+}
+/**
+ * Build a fail-closed {@link KitError} for an earn decode or review failure.
+ *
+ * Marked non-recoverable: a mismatch between what would be shown and what would
+ * be signed is never safe to retry, so the operation fails fast rather than
+ * presenting misleading decoded data. `messagePrefix` names the failing stage
+ * (calldata decode vs. review construction); callers bind it once and pass the
+ * specific failure as `message`.
+ */ function failClosedEarnError(messagePrefix, message, trace) {
+    return new KitError({
+        ...EarnError.INTERNAL_ERROR,
+        recoverability: 'FATAL',
+        message: `${messagePrefix}: ${message}`,
+        cause: {
+            trace
+        }
+    });
+}
+/**
+ * Build a {@link KitError} for a decode or consistency failure.
+ *
+ * Thin wrapper over {@link failClosedEarnError} bound to the decode-stage
+ * message prefix.
+ */ function decodeMismatchError(message, trace) {
+    return failClosedEarnError('Unable to decode earn transaction', message, trace);
+}
+/**
+ * Narrow an untyped value to a 0x-prefixed hex string, or fail fast.
+ */ function requireHex(value, path) {
+    if (typeof value === 'string' && /^0x[0-9a-fA-F]*$/.test(value)) {
+        return value;
+    }
+    throw decodeMismatchError(`${path} is not a hex string`, {
+        path,
+        value
+    });
+}
+/**
+ * Narrow an untyped value to a 20-byte EVM address, or fail fast.
+ */ function requireAddress(value, path) {
+    if (typeof value === 'string' && /^0x[0-9a-fA-F]{40}$/.test(value)) {
+        return value;
+    }
+    throw decodeMismatchError(`${path} is not an address`, {
+        path,
+        value
+    });
+}
+/**
+ * Narrow an untyped `uint256`-like value (decimal string, bigint, or integer)
+ * to a bigint, or fail fast.
+ */ function requireUint(value, path) {
+    if (typeof value === 'bigint') {
+        return value;
+    }
+    if (typeof value === 'string' && /^\d+$/.test(value)) {
+        return BigInt(value);
+    }
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
+        return BigInt(value);
+    }
+    throw decodeMismatchError(`${path} is not a uint256 value`, {
+        path,
+        value
+    });
+}
+/**
+ * Decode inner instruction calldata against the earn instruction ABI, mapping a
+ * viem decode failure (unknown selector, malformed args) to a fail-fast error.
+ */ function decodeEarnInstructionData(data, index) {
+    try {
+        return decodeFunctionData({
+            abi: earnInstructionAbi,
+            data
+        });
+    } catch (error) {
+        throw decodeMismatchError(`instructions[${index.toString()}] calldata is not a recognized earn instruction`, {
+            index,
+            selector: data.slice(0, 10),
+            error: String(error)
+        });
+    }
+}
+/**
+ * Decode Adapter `execute()` calldata, mapping a viem decode failure to a
+ * fail-fast error.
+ */ function decodeExecuteCalldata(calldata) {
+    try {
+        return decodeFunctionData({
+            abi: adapterContractAbi,
+            data: calldata
+        });
+    } catch (error) {
+        throw decodeMismatchError('encoded calldata is not a valid Adapter execute() call', {
+            error: String(error)
+        });
+    }
+}
+/**
+ * Decode one inner instruction's calldata into a typed {@link
+ * DecodedEarnInstruction}.
+ */ function decodeInstruction(instruction, index) {
+    const target = requireAddress(instruction['target'], `instructions[${index.toString()}].target`);
+    const data = requireHex(instruction['data'], `instructions[${index.toString()}].data`);
+    const decoded = decodeEarnInstructionData(data, index);
+    switch(decoded.functionName){
+        case 'deposit':
+            {
+                const [assets, receiver] = decoded.args;
+                return {
+                    method: 'deposit',
+                    vault: target,
+                    assets: assets.toString(),
+                    receiver
+                };
+            }
+        case 'withdraw':
+            {
+                const [assets, receiver, owner] = decoded.args;
+                return {
+                    method: 'withdraw',
+                    vault: target,
+                    assets: assets.toString(),
+                    receiver,
+                    owner
+                };
+            }
+        case 'redeem':
+            {
+                const [shares, receiver, owner] = decoded.args;
+                return {
+                    method: 'redeem',
+                    vault: target,
+                    shares: shares.toString(),
+                    receiver,
+                    owner
+                };
+            }
+        case 'takeFeeERC20':
+            {
+                const [token, beneficiary, fee, kitType] = decoded.args;
+                return {
+                    method: 'takeFeeERC20',
+                    feeTaker: target,
+                    token,
+                    beneficiary,
+                    fee: fee.toString(),
+                    kitType
+                };
+            }
+        case 'claim':
+            {
+                const users = decoded.args[0];
+                const tokens = decoded.args[1];
+                const amounts = decoded.args[2];
+                // Merkl claim(users, tokens, amounts, proofs) carries parallel arrays,
+                // one entry per reward. Reject any length skew rather than padding with
+                // zero amounts or dropping trailing entries, so the preview can never
+                // misstate what is claimed or for whom.
+                //
+                // Note: Merkl `amounts` are the *cumulative lifetime* total claimable per
+                // (user, token); the Distributor transfers only `amount - alreadyClaimed`.
+                // This decode faithfully surfaces the signed cumulative value, which is
+                // what `DecodedRewardClaim.amount` documents. See that type's doc.
+                if (new Set([
+                    users.length,
+                    tokens.length,
+                    amounts.length
+                ]).size !== 1) {
+                    throw decodeMismatchError(`instructions[${index.toString()}] claim has mismatched recipient/token/amount lengths`, {
+                        index,
+                        users: users.length,
+                        tokens: tokens.length,
+                        amounts: amounts.length
+                    });
+                }
+                const rewards = tokens.map((token, rewardIndex)=>({
+                        recipient: requireAddress(users[rewardIndex], `instructions[${index.toString()}].claim.users[${rewardIndex.toString()}]`),
+                        address: token,
+                        amount: requireUint(amounts[rewardIndex], `instructions[${index.toString()}].claim.amounts[${rewardIndex.toString()}]`).toString()
+                    }));
+                return {
+                    method: 'claim',
+                    distributor: target,
+                    rewards
+                };
+            }
+        /* v8 ignore next 2 -- exhaustive switch; default is unreachable */ default:
+            return assertNever$2(decoded);
+    }
+}
+/**
+ * Lift the primary values a wallet prompt cares about out of the decoded
+ * instructions into a flat summary.
+ */ function buildSummary(instructions, envelope) {
+    const summary = {};
+    instructions.forEach((instruction, index)=>{
+        switch(instruction.method){
+            case 'deposit':
+            case 'withdraw':
+            case 'redeem':
+                {
+                    // The summary lifts a single primary token movement to the top level.
+                    // An earn bundle carries exactly one deposit/withdraw/redeem today;
+                    // fail fast rather than silently overwriting an earlier one, which
+                    // would drop it from the wallet-facing preview.
+                    if (summary.token !== undefined) {
+                        throw decodeMismatchError('multiple deposit/withdraw/redeem instructions cannot be summarized into a single preview', {
+                            index
+                        });
+                    }
+                    // Pair the amount with the token it is actually denominated in so the
+                    // preview never folds two units into one entry:
+                    //  - deposit:  `assets` of the underlying asset pulled in (`tokenIn`)
+                    //  - redeem:   `shares` of the vault-share token burned (`tokenIn`)
+                    //  - withdraw: `assets` of the underlying asset paid out (`tokenOut`).
+                    //    `withdraw(assets)` counts the underlying received, not the shares
+                    //    burned to produce it, so `tokenIn` (the share token) would misstate
+                    //    the unit; the underlying is the instruction's `tokenOut`.
+                    const amount = instruction.method === 'redeem' ? instruction.shares : instruction.assets;
+                    const tokenField = instruction.method === 'withdraw' ? 'tokenOut' : 'tokenIn';
+                    summary.vault = instruction.vault;
+                    summary.receiver = instruction.receiver;
+                    summary.token = {
+                        address: requireAddress(envelope[index]?.[tokenField], `instructions[${index.toString()}].${tokenField}`),
+                        amount
+                    };
+                    break;
+                }
+            case 'takeFeeERC20':
+                {
+                    // As with the vault case, a second fee would silently overwrite the
+                    // first and understate what is charged; fail fast instead.
+                    if (summary.fee !== undefined) {
+                        throw decodeMismatchError('multiple fee instructions cannot be summarized into a single preview', {
+                            index
+                        });
+                    }
+                    summary.fee = {
+                        address: instruction.token,
+                        amount: instruction.fee
+                    };
+                    break;
+                }
+            case 'claim':
+                {
+                    // A second claim would silently drop the first from the preview
+                    // (rewards are already batched inside one Merkl claim); fail fast.
+                    if (summary.rewards !== undefined) {
+                        throw decodeMismatchError('multiple claim instructions cannot be summarized into a single preview', {
+                            index
+                        });
+                    }
+                    summary.rewards = instruction.rewards;
+                    break;
+                }
+            /* v8 ignore next 2 -- exhaustive switch; default is unreachable */ default:
+                assertNever$2(instruction);
+        }
+    });
+    return summary;
+}
+/**
+ * Vault/claim instruction methods each declared action may decode to. The
+ * mapping is many-to-one: a full withdrawal decodes to `redeem`, and any action
+ * may carry an auxiliary `takeFeeERC20` alongside its primary instruction.
+ */ const ACTION_ALLOWED_METHODS = {
+    deposit: new Set([
+        'deposit'
+    ]),
+    withdraw: new Set([
+        'withdraw',
+        'redeem'
+    ]),
+    claimRewards: new Set([
+        'claim'
+    ])
+};
+/**
+ * Fail fast when the caller-declared `action` disagrees with the decoded
+ * instructions, so the preview's headline can never mislabel what is signed
+ * (e.g. a `deposit`-labeled call handed withdraw params). `takeFeeERC20` is an
+ * auxiliary Circle-fee instruction and is allowed alongside any action.
+ */ function assertActionMatchesInstructions(action, instructions) {
+    const allowed = ACTION_ALLOWED_METHODS[action];
+    instructions.forEach((instruction, index)=>{
+        if (instruction.method === 'takeFeeERC20') {
+            return;
+        }
+        if (!allowed.has(instruction.method)) {
+            throw decodeMismatchError(`decoded instruction method '${instruction.method}' does not match the '${action}' action`, {
+                action,
+                method: instruction.method,
+                index
+            });
+        }
+    });
+}
+/**
+ * Decode a same-chain earn `execute()` bundle into a human-readable summary.
+ *
+ * Decodes every inner instruction in the service-signed `executionParams` — the
+ * same object the SDK ABI-encodes into the transaction — so the returned decode
+ * is a faithful, drift-free view of what the signer is authorizing: input token
+ * and amount, target vault, receiver, any Circle fee, and claimed rewards. Fails
+ * fast with a non-recoverable {@link KitError} if any instruction cannot be
+ * decoded, rather than returning misleading data.
+ *
+ * @param input - Action, chain, adapter, and the signed execution params.
+ * @returns The decoded transaction summary.
+ * @throws {@link KitError} If an instruction's calldata cannot be decoded.
+ *
+ * @example
+ * ```typescript
+ * const decoded = decodeEarnExecute({
+ *   action: 'deposit',
+ *   chain: 'Arc_Testnet',
+ *   adapter: '0x7fb8c7260b63934d8da38af902f87ae6e284a845',
+ *   executionParams,
+ * })
+ * // decoded.summary -> { token: { address, amount }, vault, receiver }
+ * ```
+ *
+ * @internal
+ */ function decodeEarnExecute(input) {
+    const { action, chain, adapter, executionParams } = input;
+    const envelope = requireInstructions(executionParams);
+    const instructions = envelope.map((instruction, index)=>decodeInstruction(instruction, index));
+    assertActionMatchesInstructions(action, instructions);
+    return {
+        action,
+        chain,
+        adapter,
+        instructions,
+        summary: buildSummary(instructions, envelope)
+    };
+}
+/**
+ * Assert that ABI-encoded Adapter `execute()` calldata encodes the same
+ * instruction set as the service-signed execution params.
+ *
+ * Fail-fast preview check: the SDK encodes `execute(executeParams, ...)` locally,
+ * so decoding those final bytes and comparing every field of each instruction
+ * against the signed params proves the previewed instruction set matches what
+ * will be signed. It compares `instructions[]` only — the outer `tokens`,
+ * `execId`, `deadline`, and `metadata` are not re-compared here. The
+ * authoritative integrity guarantee for the full signed struct is the on-chain
+ * EIP-712 signature verification, which reverts if any signed field is altered.
+ *
+ * @param calldata - Encoded `execute()` calldata about to be signed.
+ * @param executionParams - Service-signed execution params.
+ * @throws {@link KitError} If the calldata is not an `execute()` call or any
+ *   instruction field differs from the signed params.
+ *
+ * @example
+ * ```typescript
+ * assertEarnCalldataMatchesExecuteParams(
+ *   prepared.getCallData().data,
+ *   executionParams,
+ * )
+ * ```
+ *
+ * @internal
+ */ function assertEarnCalldataMatchesExecuteParams(calldata, executionParams) {
+    // adapterContractAbi declares only `execute`, so a successful decode is always
+    // the execute() call; a non-execute selector throws inside
+    // decodeExecuteCalldata above.
+    const decoded = decodeExecuteCalldata(calldata);
+    const encoded = decoded.args[0].instructions;
+    const signed = requireInstructions(executionParams);
+    // Compare each encoded instruction against its signed counterpart. Iterating
+    // the encoded instructions and indexing the signed set keeps both mismatch
+    // branches reachable: a signed set that is too short trips the guard below,
+    // and one that is too long trips the post-loop check.
+    encoded.forEach((instruction, index)=>{
+        const signedInstruction = signed[index];
+        if (signedInstruction === undefined) {
+            throw decodeMismatchError(`signed params are missing instruction ${index.toString()}`, {
+                index,
+                encoded: encoded.length,
+                signed: signed.length
+            });
+        }
+        const path = `instructions[${index.toString()}]`;
+        assertHexEqual(instruction.target, signedInstruction['target'], `${path}.target`);
+        assertHexEqual(instruction.data, signedInstruction['data'], `${path}.data`);
+        assertUintEqual(instruction.value, signedInstruction['value'], `${path}.value`);
+        assertHexEqual(instruction.tokenIn, signedInstruction['tokenIn'], `${path}.tokenIn`);
+        assertUintEqual(instruction.amountToApprove, signedInstruction['amountToApprove'], `${path}.amountToApprove`);
+        assertHexEqual(instruction.tokenOut, signedInstruction['tokenOut'], `${path}.tokenOut`);
+        assertUintEqual(instruction.minTokenOut, signedInstruction['minTokenOut'], `${path}.minTokenOut`);
+    });
+    if (signed.length > encoded.length) {
+        throw decodeMismatchError('signed params contain more instructions than the encoded calldata', {
+            encoded: encoded.length,
+            signed: signed.length
+        });
+    }
+}
+/**
+ * Assert two hex values are equal, case-insensitively (addresses and calldata).
+ */ function assertHexEqual(encoded, signed, path) {
+    const signedHex = requireHex(signed, path);
+    if (encoded.toLowerCase() !== signedHex.toLowerCase()) {
+        throw decodeMismatchError(`${path} differs from signed params`, {
+            path,
+            encoded,
+            signed: signedHex
+        });
+    }
+}
+/**
+ * Assert an encoded bigint equals a signed `uint256`-like value.
+ */ function assertUintEqual(encoded, signed, path) {
+    const signedUint = requireUint(signed, path);
+    if (encoded !== signedUint) {
+        throw decodeMismatchError(`${path} differs from signed params`, {
+            path,
+            encoded: encoded.toString(),
+            signed: signedUint.toString()
+        });
+    }
+}
+
+/**
+ * Namespaced discriminator for the EarnKit authorization review.
+ *
+ * Applications match on this in an adapter `onBeforeAuthorize` hook to decide
+ * whether the request carries EarnKit semantic data. Prefer the
+ * {@link isEarnExecuteReview} type guard over comparing this string directly.
+ *
+ * @example
+ * ```typescript
+ * if (review?.kind === EARN_EXECUTE_REVIEW_KIND) { … }
+ * ```
+ */ const EARN_EXECUTE_REVIEW_KIND = 'earn.execute';
+
+/**
+ * Build a fail-closed {@link KitError} for a review-construction failure.
+ *
+ * Marked non-recoverable: a review that cannot prove the calldata matches the
+ * signed operation must abort authorization, never retry with misleading data.
+ */ function reviewError(message, trace) {
+    return failClosedEarnError('Unable to build earn authorization review', message, trace);
+}
+/**
+ * Narrow the canonical authorization payload to the single Adapter `execute()`
+ * call a same-chain earn operation authorizes.
+ *
+ * Same-chain deposit, withdraw, and claim-rewards each authorize exactly one
+ * `evm-calls` payload carrying one call. Anything else (typed data, a batch,
+ * an empty call list) means this descriptor was attached to the wrong
+ * authorization unit, so fail closed rather than decode misleading data.
+ */ function assertSingleEvmCallPayload(payload) {
+    if (payload.type !== 'evm-calls') {
+        throw reviewError(`expected an 'evm-calls' payload but received '${payload.type}'`, {
+            type: payload.type
+        });
+    }
+    const [call, ...rest] = payload.calls;
+    if (call === undefined) {
+        throw reviewError('the evm-calls payload contains no calls to review', {
+            callCount: payload.calls.length
+        });
+    }
+    if (rest.length > 0) {
+        throw reviewError('a same-chain earn operation authorizes exactly one Adapter execute() call', {
+            callCount: payload.calls.length
+        });
+    }
+    return call;
+}
+/**
+ * Select the final earn `execute()` call from an atomic Earn batch.
+ *
+ * Same-chain batched deposit/withdraw authorizes either `[execute]` when the
+ * current allowance is sufficient, or `[approve, execute]` when a top-up is
+ * required. Any other shape means the descriptor was attached to an
+ * unexpected authorization unit, so fail closed.
+ */ function assertBatchedEarnExecuteCall(payload) {
+    if (payload.type !== 'evm-calls') {
+        throw reviewError(`expected an 'evm-calls' payload but received '${payload.type}'`, {
+            type: payload.type
+        });
+    }
+    if (payload.calls.length !== 1 && payload.calls.length !== 2) {
+        throw reviewError('a batched earn operation authorizes [execute] or [approve, execute]', {
+            callCount: payload.calls.length
+        });
+    }
+    const executeCall = payload.calls.at(-1);
+    if (executeCall === undefined) {
+        throw reviewError('the earn batch contains no execute call to review', {
+            callCount: payload.calls.length
+        });
+    }
+    return executeCall;
+}
+/**
+ * Map a canonical {@link EvmCall} to the {@link EarnEncodedTransaction} preview
+ * shape, failing closed when the earn `execute()` call carries no calldata.
+ */ function toEarnEncodedTransaction(call) {
+    if (call.data === undefined) {
+        throw reviewError('the earn execute() call is missing calldata', {
+            to: call.to
+        });
+    }
+    return {
+        to: call.to,
+        data: call.data,
+        ...call.value !== undefined && {
+            value: call.value
+        }
+    };
+}
+/**
+ * Create an Earn authorization descriptor using the supplied canonical-payload
+ * call selector.
+ *
+ * @param input - The action, chain, and service-signed execution params.
+ * @param selectCall - Fail-closed selector for the execute call under review.
+ * @returns A lazy descriptor that decodes and verifies the selected call.
+ *
+ * @internal
+ */ function createEarnExecuteDescriptor(input, selectCall) {
+    const { action, chain, executionParams } = input;
+    const createReview = (payload)=>{
+        const call = selectCall(payload);
+        const encoded = toEarnEncodedTransaction(call);
+        const decoded = decodeEarnExecute({
+            action,
+            chain,
+            adapter: encoded.to,
+            executionParams
+        });
+        // Prove the calldata about to be signed encodes the same instruction set as
+        // the service-signed params. Throwing here aborts before the wallet prompt.
+        assertEarnCalldataMatchesExecuteParams(encoded.data, executionParams);
+        const review = {
+            kind: EARN_EXECUTE_REVIEW_KIND,
+            data: {
+                encoded,
+                decoded
+            }
+        };
+        return review;
+    };
+    return {
+        createReview
+    };
+}
+/**
+ * Build the lazy `earn.execute` authorization descriptor for a same-chain earn
+ * action.
+ *
+ * The returned descriptor carries only a `createReview` factory — no intent
+ * override, because the adapter's action system supplies the intent from the
+ * action key. The factory is evaluated at most once, and only when the
+ * application configured an adapter `onBeforeAuthorize` hook. When it runs it:
+ *
+ * 1. narrows the canonical payload to its single Adapter `execute()` call;
+ * 2. lifts that call into an {@link EarnEncodedTransaction};
+ * 3. decodes it into a `DecodedEarnTx`; and
+ * 4. asserts the decoded calldata matches the service-signed params, throwing
+ *    (aborting authorization before the wallet or signer) on any mismatch.
+ *
+ * @param input - The action, chain, and service-signed execution params.
+ * @returns An authorization descriptor to pass as the fourth `prepareAction`
+ *   argument for the final earn action only (never the allowance approval).
+ * @throws {@link KitError} From the review factory when the payload is not a
+ *   single earn `execute()` call or the calldata diverges from the signed
+ *   params. The throw surfaces through the adapter gate before authorization.
+ *
+ * @example
+ * ```typescript
+ * const descriptor = buildEarnExecuteDescriptor({
+ *   action: 'deposit',
+ *   chain: 'Arc_Testnet',
+ *   executionParams,
+ * })
+ * await adapter.prepareAction('earn.deposit', actionParams, ctx, {
+ *   authorization: descriptor,
+ * })
+ * ```
+ *
+ * @internal
+ */ function buildEarnExecuteDescriptor(input) {
+    return createEarnExecuteDescriptor(input, assertSingleEvmCallPayload);
+}
+/**
+ * Build a lazy `earn.execute` authorization descriptor for an atomic Earn
+ * batch containing either `[execute]` or `[approve, execute]`.
+ *
+ * The review always decodes and verifies the final call against the
+ * service-signed execution params. Unexpected payload types and call counts
+ * fail closed before wallet authorization.
+ *
+ * @param input - The action, chain, and service-signed execution params.
+ * @returns A descriptor suitable for `batchExecute` authorization options.
+ * @throws {@link KitError} From the lazy review factory when the batch shape or
+ *   final execute calldata cannot be verified.
+ *
+ * @internal
+ */ function buildBatchedEarnExecuteDescriptor(input) {
+    return createEarnExecuteDescriptor(input, assertBatchedEarnExecuteCall);
+}
+/**
+ * Type guard: narrow an adapter authorization review to an EarnKit
+ * `earn.execute` review.
+ *
+ * Use this inside an adapter `onBeforeAuthorize` hook to detect whether the
+ * request carries EarnKit semantic data before reading it, instead of
+ * comparing `review.kind` by hand. Robust against plain-JavaScript callers:
+ * accepts `unknown` and checks the shape at runtime.
+ *
+ * @param review - The `review` field from an `AuthorizationRequest`, or any
+ *   value.
+ * @returns `true` when `review` is an `earn.execute` review with the expected
+ *   `{ encoded, decoded }` data shape.
+ *
+ * @example
+ * ```typescript
+ * onBeforeAuthorize: async ({ review }) => {
+ *   if (isEarnExecuteReview(review)) {
+ *     await showEarnConfirmation(review.data.decoded.summary)
+ *   }
+ *   return 'approve'
+ * }
+ * ```
+ */ function isEarnExecuteReview(review) {
+    if (typeof review !== 'object' || review === null) {
+        return false;
+    }
+    const candidate = review;
+    if (candidate.kind !== EARN_EXECUTE_REVIEW_KIND) {
+        return false;
+    }
+    const data = candidate.data;
+    if (typeof data !== 'object' || data === null) {
+        return false;
+    }
+    const { encoded, decoded } = data;
+    return typeof encoded === 'object' && encoded !== null && typeof decoded === 'object' && decoded !== null;
+}
+
 /**
  * Prepare an earn adapter action, execute it, wait for confirmation, and
  * throw a structured revert error if the receipt status is `'reverted'`.
@@ -32760,16 +34071,37 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
  *   address,
  *   actionKey: 'earn.deposit',
  *   actionParams: { executeParams, tokenInputs, signature },
+ *   action: 'deposit',
+ *   executionParams,
  *   revertMessage: 'Earn deposit reverted on-chain',
  * })
  * ```
  *
  * @internal
  */ async function executeEarnAction(params) {
-    const { adapter, chain, address, actionKey, actionParams, revertMessage } = params;
+    const { adapter, chain, address, actionKey, actionParams, action, executionParams, revertMessage } = params;
+    // Attach the lazy `earn.execute` review to the final earn action only (never
+    // the allowance approval, which runs on a separate path). The adapter's
+    // action system supplies the intent from `actionKey`, so the descriptor
+    // carries only the review factory. The factory is evaluated at most once,
+    // and only when the application configured an `onBeforeAuthorize` hook.
+    const authorization = buildEarnExecuteDescriptor({
+        action,
+        // The provider validates the chain is Earn-supported in
+        // `resolveAdapterContext` before reaching execute, so the concrete chain
+        // identifier is a valid `EarnChainIdentifier`. It is carried through to the
+        // decoded preview's display `chain` field only.
+        chain: chain.chain,
+        executionParams
+    });
+    // The abstract `Adapter.prepareAction` is 3-arg; the fourth authorization
+    // argument lives on the `withLegacyCompat` wrapper that produced the concrete
+    // adapter passed here. Narrow the single seam that threads the descriptor.
     const prepared = await adapter.prepareAction(actionKey, actionParams, {
         chain,
         address
+    }, {
+        authorization
     });
     const gasLimitOverride = await estimateBufferedGasLimit(prepared);
     const txHash = prepared.type === 'evm' && gasLimitOverride !== undefined ? await prepared.execute({
@@ -32794,6 +34126,278 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
     };
 }
 
+/**
+ * Decide whether a same-chain earn action should be submitted as a single
+ * atomic batch.
+ *
+ * Returns `true` only when the consumer has not opted out
+ * (`batchTransactions !== false`), the source chain is EVM, the adapter
+ * structurally exposes the shared batch methods, and the wallet reports atomic
+ * batch support. `address` is forwarded as `fromAddress` so developer-controlled
+ * adapters can probe the specific wallet. Any thrown capability probe is
+ * treated as "no support".
+ *
+ * @param params - Adapter, chain, address, and the resolved `batchTransactions` flag.
+ * @returns `true` when batched execution should be attempted.
+ *
+ * @example
+ * ```typescript
+ * if (await shouldUseBatchedEarnAction({ adapter, chain, address, batchTransactions })) {
+ *   // take the batched approve + execute path
+ * }
+ * ```
+ *
+ * @internal
+ */ async function shouldUseBatchedEarnAction(params) {
+    const { adapter, chain, address, batchTransactions } = params;
+    if (batchTransactions === false) {
+        return false;
+    }
+    if (chain.type !== 'evm') {
+        return false;
+    }
+    const candidate = adapter;
+    if (typeof candidate.supportsAtomicBatch !== 'function' || typeof candidate.batchExecute !== 'function') {
+        return false;
+    }
+    try {
+        return await candidate.supportsAtomicBatch(chain, {
+            fromAddress: address
+        });
+    } catch  {
+        return false;
+    }
+}
+async function buildSuccessfulBatchResult(adapter, chain, receipt, batchId, revertMessage) {
+    const transaction = {
+        txHash: receipt.txHash,
+        explorerUrl: buildExplorerUrl(chain, receipt.txHash)
+    };
+    let confirmed;
+    try {
+        confirmed = await adapter.waitForTransaction(receipt.txHash, {
+            confirmations: 1
+        }, chain);
+    } catch  {
+        // The batch adapter already confirmed success. Receipt enrichment is
+        // telemetry-only, so an additional RPC failure must not turn an accepted
+        // money-moving operation into a retryable business failure.
+        return transaction;
+    }
+    if (confirmed.status === 'reverted') {
+        throw createTransactionRevertedError(chain.name, revertMessage, {
+            batchId
+        }, receipt.txHash, transaction.explorerUrl);
+    }
+    return {
+        ...transaction,
+        ...confirmed.gasUsed !== undefined && {
+            gasUsed: confirmed.gasUsed
+        },
+        ...confirmed.effectiveGasPrice !== undefined && {
+            effectiveGasPrice: confirmed.effectiveGasPrice
+        }
+    };
+}
+function throwBatchFailure(result, executeReceipt, chain, actionKey, revertMessage) {
+    const cause = result.error;
+    if (result.statusCode === 400) {
+        throw new KitError({
+            ...RpcError.ENDPOINT_ERROR,
+            recoverability: 'RETRYABLE',
+            message: `Batched earn ${actionKey} failed off-chain before inclusion (batch ${result.batchId}).`,
+            cause: {
+                trace: {
+                    batchId: result.batchId,
+                    statusCode: result.statusCode,
+                    cause
+                }
+            }
+        });
+    }
+    const causeTrace = cause instanceof KitError && typeof cause.cause?.trace === 'object' && cause.cause.trace !== null ? cause.cause.trace : undefined;
+    if (cause instanceof KitError && causeTrace?.['kind'] === 'failed_offchain') {
+        throw cause;
+    }
+    const isConfirmedRevert = cause instanceof KitError && cause.name === OnchainError.TRANSACTION_REVERTED.name || result.statusCode === 500 || result.statusCode === 600 || result.statusCode === undefined && cause === undefined && executeReceipt?.status === 'error' && executeReceipt.txHash !== '';
+    if (isConfirmedRevert) {
+        throw createTransactionRevertedError(chain.name, revertMessage, {
+            batchId: result.batchId,
+            error: cause
+        });
+    }
+    throw new KitError({
+        ...NetworkError.TIMEOUT,
+        recoverability: 'FATAL',
+        message: `Batched earn ${actionKey} was submitted (batch ${result.batchId}) but its outcome could not be confirmed; check the transaction status before retrying.`,
+        cause: {
+            trace: {
+                batchId: result.batchId,
+                cause
+            }
+        }
+    });
+}
+/**
+ * Execute the `approve` and `execute` steps of a same-chain earn action as a
+ * single atomic batch.
+ *
+ * Prepare both `PreparedChainRequest` objects upfront, extract their raw call
+ * data via `getCallData()`, then submit both through the adapter's shared
+ * `batchExecute`. `address` is forwarded as `opts.fromAddress` so
+ * developer-controlled adapters batch on behalf of the right wallet;
+ * `idempotencyKey` is forwarded for adapters that deduplicate ambiguous
+ * submissions (the Circle developer-controlled adapter reuses the Earn
+ * execution id); other adapters may ignore either option. Reused by both the
+ * deposit and withdraw flows via the `actionKey` parameter.
+ *
+ * @param params - Adapter, chain, action key, signed payload, and approval inputs.
+ * @returns The confirmed execute transaction hash, explorer URL, and receipt
+ *   gas data when the adapter can retrieve it.
+ * @throws {@link KitError} when the source chain is not EVM.
+ * @throws {@link KitError} when calldata extraction (`getCallData`) is not
+ *   supported by the prepared requests.
+ * @throws {@link KitError} when the batch reverts on-chain (a confirmed
+ *   terminal revert), carrying `batchId`.
+ * @throws {@link KitError} RETRYABLE when EIP-5792 reports an off-chain
+ *   failure carrying `batchId` and status code `400`; no call was included.
+ * @throws {@link KitError} FATAL `NetworkError.TIMEOUT` when the batch was
+ *   submitted but its outcome could not be confirmed (poll timeout or any
+ *   other non-revert post-submission failure); carries `batchId` so the caller
+ *   can check transaction status before retrying.
+ * @remarks
+ * Once the batch has been submitted this function does not fall back to the
+ * sequential path — the batch is already on its way, so a fallback would risk
+ * double-spend. Post-submission failures surface through the adapter's batch
+ * result: a confirmed on-chain revert (Circle: a `TRANSACTION_REVERTED` cause;
+ * Viem: status code `500`/`600`) is thrown as a revert error, status code `400`
+ * is reported as a retryable off-chain failure, and any other unconfirmed
+ * outcome is thrown as a FATAL timeout error carrying `batchId`.
+ *
+ * @example
+ * ```typescript
+ * const { txHash, explorerUrl } = await executeBatchedEarnAction({
+ *   adapter,
+ *   chain,
+ *   address,
+ *   actionKey: 'earn.deposit',
+ *   executeParams,
+ *   tokenInputs,
+ *   signature,
+ *   approvalToken: usdcAddress,
+ *   delegate: adapterContractAddress,
+ *   requiredAllowance: 1_000_000n,
+ *   idempotencyKey: '550e8400-e29b-41d4-a716-446655440000',
+ *   revertMessage: 'Earn deposit reverted on-chain',
+ * })
+ * ```
+ *
+ * @internal
+ */ async function executeBatchedEarnAction(params) {
+    const { adapter, chain, address, actionKey, executeParams, tokenInputs, signature, approvalToken, delegate, requiredAllowance, idempotencyKey, revertMessage } = params;
+    if (chain.type !== 'evm') {
+        throw new KitError({
+            ...InputError.INVALID_CHAIN,
+            recoverability: 'FATAL',
+            message: 'Batched earn execution is only supported on EVM chains.'
+        });
+    }
+    const evmChain = chain;
+    const batchAdapter = adapter;
+    // Read the current allowance so the approval tops up only the missing amount.
+    // When the existing allowance already covers the payload, skip the approve
+    // call and batch only the execute — this mirrors the sequential
+    // approveAllowanceIfNeeded guard and avoids an increaseAllowance underflow
+    // (requiredAllowance - currentAllowance would be negative, which reverts as
+    // an out-of-range uint256).
+    const allowancePrepared = await adapter.prepareAction('token.allowance', {
+        tokenAddress: approvalToken,
+        delegate
+    }, {
+        chain,
+        address
+    });
+    const currentAllowance = parseAllowanceResponse(await allowancePrepared.execute());
+    const approvalNeeded = currentAllowance < requiredAllowance;
+    const executePrepared = await adapter.prepareAction(actionKey, {
+        executeParams,
+        tokenInputs,
+        signature
+    }, {
+        chain,
+        address
+    });
+    const approvePrepared = approvalNeeded ? await prepareApprovalAction({
+        adapter,
+        chain,
+        address,
+        tokenAddress: approvalToken,
+        delegate,
+        currentAllowance,
+        requiredAllowance
+    }) : undefined;
+    if (executePrepared.type !== 'evm' || !executePrepared.getCallData) {
+        throw new KitError({
+            ...InputError.UNSUPPORTED_ACTION,
+            recoverability: 'FATAL',
+            message: 'Batched earn execution requires EVM prepared requests with getCallData() support.'
+        });
+    }
+    if (approvePrepared !== undefined && (approvePrepared.type !== 'evm' || !approvePrepared.getCallData)) {
+        throw new KitError({
+            ...InputError.UNSUPPORTED_ACTION,
+            recoverability: 'FATAL',
+            message: 'Batched earn execution requires EVM prepared requests with getCallData() support.'
+        });
+    }
+    const executeCallData = executePrepared.getCallData();
+    // Prepend the approve call only when an allowance top-up is required.
+    const calls = approvePrepared?.type === 'evm' && approvePrepared.getCallData ? [
+        approvePrepared.getCallData(),
+        executeCallData
+    ] : [
+        executeCallData
+    ];
+    const authorization = buildBatchedEarnExecuteDescriptor({
+        action: actionKey === 'earn.deposit' ? 'deposit' : 'withdraw',
+        chain: evmChain.chain,
+        executionParams: executeParams
+    });
+    const result = await batchAdapter.batchExecute(calls, evmChain, {
+        fromAddress: address,
+        idempotencyKey,
+        atomicRequired: true,
+        authorization
+    });
+    // Success fans one confirmed hash across every receipt; the execute call is
+    // the last one (approve, if present, precedes it). On failure a confirming
+    // adapter returns no receipts, so a missing/non-success last receipt — or a
+    // populated `result.error` — means the batch failed after submission (point
+    // of no return). We never fall back, which would double-spend.
+    const receiptCountMatches = result.receipts.length === calls.length;
+    const executeReceipt = receiptCountMatches ? result.receipts[calls.length - 1] : undefined;
+    const succeeded = receiptCountMatches && (result.statusCode === undefined || result.statusCode === 200) && result.error === undefined && executeReceipt?.status === 'success' && executeReceipt.txHash !== '';
+    if (succeeded) {
+        return buildSuccessfulBatchResult(adapter, evmChain, executeReceipt, result.batchId, revertMessage);
+    }
+    // Distinguish an off-chain rejection, a confirmed on-chain revert, and an
+    // unknown outcome across both adapter conventions that share this contract:
+    //   - Circle SCA: no receipts + `error`; its trace kind identifies an
+    //     off-chain rejection, confirmed revert, or unconfirmed outcome.
+    //   - Viem EIP-5792: statusCode 500/600 explicitly confirms an on-chain
+    //     full/partial revert.
+    //   - Legacy/string-status wallets: a real-hash error receipt with no cause
+    //     is the best available confirmed-revert signal.
+    // statusCode 400 is terminal but off-chain: the wallet confirms no call was
+    // included, so it must not be labeled as a revert or unknown outcome.
+    // Anything else — a poll timeout or any other post-submission failure with no
+    // confirmed-revert signal — means the batch was submitted but its fate is
+    // unconfirmed. Surface that as a FATAL (non-auto-retry) error carrying
+    // `batchId` so the caller checks status before retrying, rather than
+    // mislabeling it a revert.
+    return throwBatchFailure(result, executeReceipt, evmChain, actionKey, revertMessage);
+}
+
 /**
  * Validate that a service-signed execution payload has not expired before
  * the SDK asks the wallet to broadcast a transaction.
@@ -34090,7 +35694,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
 }
 
 var name$1 = "@circle-fin/provider-earn-service";
-var version$1 = "1.3.1";
+var version$1 = "1.4.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -35728,6 +37332,46 @@ function finishElapsedWait(lastStatus, lastError) {
             const approvalToken = resolveEarnApprovalToken(executionParams);
             const tokenInputs = approvalToken === undefined ? [] : buildEarnTokenInputs(executionParams, approvalToken);
             const requiredAllowance = sumTokenInputAmounts(tokenInputs);
+            const approvalNeeded = !options.skipApprove && approvalToken !== undefined && requiredAllowance > 0n;
+            // Batch-capable wallets bundle approve + deposit into one atomic
+            // submission. Only attempt this when an approval is actually needed.
+            if (approvalNeeded && approvalToken !== undefined && await shouldUseBatchedEarnAction({
+                adapter,
+                chain,
+                address,
+                batchTransactions: config?.batchTransactions
+            })) {
+                const { txHash, explorerUrl } = await this.runPhase(ctx, 'deposit', 'execute', async ()=>{
+                    try {
+                        const result = await executeBatchedEarnAction({
+                            adapter,
+                            chain,
+                            address,
+                            actionKey: 'earn.deposit',
+                            executeParams: executionParams,
+                            tokenInputs,
+                            signature,
+                            approvalToken,
+                            delegate: adapterContractAddress,
+                            requiredAllowance,
+                            idempotencyKey: execId,
+                            revertMessage: 'Earn deposit reverted on-chain'
+                        });
+                        reportTransactionSuccess(transactionReportContext, 'Deposit', result);
+                        return result;
+                    } catch (error) {
+                        reportTransactionFailure(transactionReportContext, 'Deposit', error);
+                        throw error;
+                    }
+                }, ({ txHash })=>txHash);
+                return {
+                    kind: 'same-chain',
+                    txHash,
+                    explorerUrl,
+                    vaultAddress,
+                    amount: params.amount
+                };
+            }
             if (!options.skipApprove && approvalToken !== undefined && requiredAllowance > 0n) {
                 await this.runPhase(ctx, 'approve', 'approve', async ()=>{
                     try {
@@ -35760,6 +37404,8 @@ function finishElapsedWait(lastStatus, lastError) {
                             tokenInputs,
                             signature
                         },
+                        action: 'deposit',
+                        executionParams,
                         revertMessage: 'Earn deposit reverted on-chain'
                     });
                     reportTransactionSuccess(transactionReportContext, 'Deposit', result);
@@ -35891,6 +37537,44 @@ function finishElapsedWait(lastStatus, lastError) {
             const tokenInputs = buildEarnTokenInputs(executionParams, vaultAddress);
             const approvalToken = tokenInputs[0]?.token;
             const requiredAllowance = sumTokenInputAmounts(tokenInputs);
+            // Batch-capable wallets bundle approve + withdraw into one atomic
+            // submission. Only attempt this when an approval is actually needed.
+            if (!options.skipApprove && approvalToken !== undefined && requiredAllowance > 0n && await shouldUseBatchedEarnAction({
+                adapter,
+                chain,
+                address,
+                batchTransactions: config?.batchTransactions
+            })) {
+                const { txHash, explorerUrl } = await this.runPhase(ctx, 'withdraw', 'execute', async ()=>{
+                    try {
+                        const result = await executeBatchedEarnAction({
+                            adapter,
+                            chain,
+                            address,
+                            actionKey: 'earn.withdraw',
+                            executeParams: executionParams,
+                            tokenInputs,
+                            signature,
+                            approvalToken,
+                            delegate: adapterContractAddress,
+                            requiredAllowance,
+                            idempotencyKey: execId,
+                            revertMessage: 'Earn withdraw reverted on-chain'
+                        });
+                        reportTransactionSuccess(transactionReportContext, 'Withdraw', result);
+                        return result;
+                    } catch (error) {
+                        reportTransactionFailure(transactionReportContext, 'Withdraw', error);
+                        throw error;
+                    }
+                }, ({ txHash })=>txHash);
+                return {
+                    txHash,
+                    explorerUrl,
+                    vaultAddress,
+                    amount: params.amount
+                };
+            }
             if (!options.skipApprove && approvalToken !== undefined) {
                 await this.runPhase(ctx, 'approve', 'approve', async ()=>{
                     try {
@@ -35923,6 +37607,8 @@ function finishElapsedWait(lastStatus, lastError) {
                             tokenInputs,
                             signature
                         },
+                        action: 'withdraw',
+                        executionParams,
                         revertMessage: 'Earn withdraw reverted on-chain'
                     });
                     reportTransactionSuccess(transactionReportContext, 'Withdraw', result);
@@ -36002,6 +37688,8 @@ function finishElapsedWait(lastStatus, lastError) {
                         tokenInputs: [],
                         signature
                     },
+                    action: 'claimRewards',
+                    executionParams,
                     revertMessage: 'Earn claim rewards reverted on-chain'
                 }), ({ txHash })=>txHash);
             return {
@@ -36685,11 +38373,16 @@ const sourceAdapterContextSchema = z.object({
  *
  * Validate the optional Kit Key field using the standard `apiKeySchema`
  * format (`KIT_KEY:<keyId>:<keySecret>`). When omitted, the SDK
- * operates in permissionless mode.
+ * operates in permissionless mode. `baseUrl` overrides the Earn Service
+ * endpoint (e.g. staging); `batchTransactions: false` opts out of atomic
+ * batched execution. Both are forwarded to the provider, so this `.strict()`
+ * schema must accept them or a valid config object is rejected.
  *
  * @internal
  */ const earnConfigSchema = z.object({
-    kitKey: apiKeySchema.optional()
+    kitKey: apiKeySchema.optional(),
+    baseUrl: z.string().optional(),
+    batchTransactions: z.boolean().optional()
 }).strict();
 /**
  * Canonical decimal form: a leading digit with no leading zeros (a single
@@ -39866,7 +41559,7 @@ async function deposit$2(context, params) {
 }
 
 var name = "@circle-fin/unified-balance-kit";
-var version = "1.3.1";
+var version = "1.4.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -41207,7 +42900,8 @@ function throwNetworkMismatch(expected, actual) {
     };
 }
 /**
- * Group intents by adapter and chain for signing (Solana one-per-intent, EVM batched by adapter).
+ * Group intents for signing (Solana one-per-intent, EVM batched by adapter
+ * with every source chain retained by Gateway domain).
  *
  * @param intents - Burn intents from estimate response.
  * @param allocations - Normalized allocations used to map domain → adapter/chain.
@@ -42584,22 +44278,32 @@ const DEFAULT_GAS_FEE = parseUnits('0.1', USDC_DECIMALS);
  *
  * Single-intent sets become one burnIntent + signature; multi-intent sets become burnIntentSet + signature.
  *
+ * Sets flagged `contractSigner` carry `contractSigner: true`, which tells
+ * Gateway to validate the signature with ERC-1271 (an offchain
+ * `isValidSignature` simulation) instead of `ecrecover`. The flag is
+ * omitted for EOA signers so their payloads stay byte-identical.
+ *
  * @param signedSets - Signed intent sets (intents + signature per signer).
  * @returns Array of transfer payloads for POST /v1/transfer.
  */ function buildTransferRequestBody(signedSets) {
     return signedSets.map((set)=>{
         const firstIntent = set.intents[0];
+        const contractSigner = set.contractSigner === true ? {
+            contractSigner: true
+        } : {};
         if (set.intents.length === 1 && firstIntent) {
             return {
                 burnIntent: serializeBurnIntent(firstIntent),
-                signature: set.signature
+                signature: set.signature,
+                ...contractSigner
             };
         }
         return {
             burnIntentSet: {
                 intents: set.intents.map(serializeBurnIntent)
             },
-            signature: set.signature
+            signature: set.signature,
+            ...contractSigner
         };
     });
 }
@@ -42962,11 +44666,16 @@ const BPS_DIVISOR = 100_000n;
     return required;
 }
 
+function requireEvmChainsByDomain(group) {
+    if (group.chainsByDomain !== undefined) return group.chainsByDomain;
+    throw createValidationFailedError$1('adapterGroup.chainsByDomain', group.chainsByDomain, 'must be provided for an EVM adapter group');
+}
 /**
- * Sign each adapter group: Solana one intent per signature, EVM batch per adapter.
+ * Sign each adapter group: Solana one intent per signature, and EVM either
+ * batched for EOAs or split by source chain for ERC-1271 signers.
  *
  * @param adapterGroups - Groups from groupIntentsByAdapter.
- * @returns Promise of signed sets (intents + signature) for buildTransferRequestBody.
+ * @returns Promise of signed sets for buildTransferRequestBody.
  *
  * @example
  * ```typescript
@@ -42979,9 +44688,10 @@ const BPS_DIVISOR = 100_000n;
         if (group.chain.type === 'solana') {
             return signSolanaIntentGroup(group);
         }
-        return [
-            await signEvmIntentGroup(group)
-        ];
+        return await signEvmIntentGroup({
+            ...group,
+            chainsByDomain: requireEvmChainsByDomain(group)
+        });
     }));
     return nested.flat();
 }
@@ -43631,7 +45341,8 @@ async function runSpendNormalPath(params, destChain, useForwarder, dispatcher, s
             signedSetCount: signedSets.length,
             signatures: signedSets.map((s)=>({
                     intentCount: s.intents.length,
-                    signature: s.signature
+                    signature: s.signature,
+                    contractSigner: s.contractSigner === true
                 }))
         }
     });
@@ -47257,6 +48968,33 @@ registerKit(`${pkg.name}/${pkg.version}`);
     }
 }
 
+const APP_KIT_CUSTOM_FEE_POLICY_KEYS = new Set([
+    'bridge',
+    'swap',
+    'unifiedBalance'
+]);
+function assertAppKitCustomFeePolicy(policy) {
+    if (policy === null || typeof policy !== 'object' || Array.isArray(policy)) {
+        throw createValidationFailedError$1('policy', policy, 'AppKit custom fee policy must be an object');
+    }
+    for (const key of Object.keys(policy)){
+        if (!APP_KIT_CUSTOM_FEE_POLICY_KEYS.has(key)) {
+            throw createValidationFailedError$1(`policy.${key}`, key, 'AppKit custom fee policy only supports bridge, swap, and unifiedBalance');
+        }
+    }
+    const candidate = policy;
+    if (candidate.bridge !== undefined) {
+        assertCustomFeePolicy$2(candidate.bridge);
+    }
+    if (candidate.swap !== undefined) {
+        assertCustomFeePolicy$1(candidate.swap);
+    }
+}
+function assertAppKitCustomFeePolicyScope(operation) {
+    if (typeof operation !== 'string' || !APP_KIT_CUSTOM_FEE_POLICY_KEYS.has(operation)) {
+        throw createValidationFailedError$1('operation', operation, 'AppKit custom fee policy operation must be bridge, swap, or unifiedBalance');
+    }
+}
 /**
  * A high-level SDK for stablecoin operations, including bridging, swapping, and earn.
  *
@@ -47379,13 +49117,10 @@ registerKit(`${pkg.name}/${pkg.version}`);
    * })
    * ```
    */ constructor(config = {}){
-        this.context = createContext({
-            ...config,
-            ...config.disableErrorReporting != null && {
-                disableErrorReporting: config.disableErrorReporting
-            }
-        });
-        this.unifiedBalance = new AppKitUnifiedBalance({
+        if (config.customFeePolicy !== undefined) {
+            assertAppKitCustomFeePolicy(config.customFeePolicy);
+        }
+        const unifiedBalance = new AppKitUnifiedBalance({
             ...config.unifiedBalance,
             ...config.disableErrorReporting != null && {
                 disableErrorReporting: config.disableErrorReporting
@@ -47394,6 +49129,16 @@ registerKit(`${pkg.name}/${pkg.version}`);
                 disableAnalytics: config.disableAnalytics
             }
         });
+        if (config.customFeePolicy?.unifiedBalance != null) {
+            unifiedBalance.setCustomFeePolicy(config.customFeePolicy.unifiedBalance);
+        }
+        this.context = createContext({
+            ...config,
+            ...config.disableErrorReporting != null && {
+                disableErrorReporting: config.disableErrorReporting
+            }
+        });
+        this.unifiedBalance = unifiedBalance;
         this.earn = {
             // A single implementation cannot satisfy the per-branch deposit
             // overloads, so assert the overloaded interface shape; the
@@ -47837,6 +49582,77 @@ registerKit(`${pkg.name}/${pkg.version}`);
    */ getSupportedChains(operationType) {
         return getSupportedChains$2(this.context, operationType, this.unifiedBalance);
     }
+    /**
+   * Set operation-scoped custom fee policies.
+   *
+   * Configure custom fees for only the operations that need them. Bridge and
+   * swap policies are forwarded to the underlying kits when those operations
+   * run. Unified balance policies are applied immediately to the namespaced
+   * Unified Balance Kit.
+   *
+   * @param policy - Partial custom fee policy grouped by operation.
+   * @returns Nothing.
+   * @throws \{KitError\} If `policy` or a provided operation policy is invalid.
+   *
+   * @example
+   * ```typescript
+   * kit.setCustomFeePolicy({
+   *   bridge: {
+   *     computeFee: () => '1.00',
+   *     resolveFeeRecipientAddress: () => '0x1234567890123456789012345678901234567890',
+   *   },
+   * })
+   * ```
+   */ setCustomFeePolicy(policy) {
+        assertAppKitCustomFeePolicy(policy);
+        if (policy.unifiedBalance != null) {
+            this.unifiedBalance.setCustomFeePolicy(policy.unifiedBalance);
+        }
+        this.context.customFeePolicy = {
+            ...this.context.customFeePolicy,
+            ...policy
+        };
+    }
+    /**
+   * Remove an AppKit-level custom fee policy for one operation.
+   *
+   * Bridge and swap policies are removed from AppKit's persistent context so
+   * future operations fall back to legacy fee hooks. Unified balance policies
+   * are also removed from the namespaced Unified Balance Kit.
+   *
+   * @param operation - Operation whose custom fee policy should be removed.
+   * @returns Nothing.
+   * @throws \{KitError\} If `operation` is invalid.
+   *
+   * @example
+   * ```typescript
+   * kit.removeCustomFeePolicy('bridge')
+   * ```
+   */ removeCustomFeePolicy(operation) {
+        assertAppKitCustomFeePolicyScope(operation);
+        if (operation === 'unifiedBalance') {
+            this.unifiedBalance.removeCustomFeePolicy();
+        }
+        if (this.context.customFeePolicy == null) {
+            return;
+        }
+        const currentPolicy = this.context.customFeePolicy;
+        const nextPolicy = {};
+        if (operation !== 'bridge' && currentPolicy.bridge !== undefined) {
+            nextPolicy.bridge = currentPolicy.bridge;
+        }
+        if (operation !== 'swap' && currentPolicy.swap !== undefined) {
+            nextPolicy.swap = currentPolicy.swap;
+        }
+        if (operation !== 'unifiedBalance' && currentPolicy.unifiedBalance !== undefined) {
+            nextPolicy.unifiedBalance = currentPolicy.unifiedBalance;
+        }
+        if (Object.keys(nextPolicy).length === 0) {
+            delete this.context.customFeePolicy;
+            return;
+        }
+        this.context.customFeePolicy = nextPolicy;
+    }
     on(actionOrWildCard, handler) {
         const action = actionOrWildCard;
         const typedHandler = handler;
@@ -47891,5 +49707,5 @@ registerKit(`${pkg.name}/${pkg.version}`);
     }
 }
 
-export { AppKit, BalanceError, Blockchain, BridgeChain, EarnChain, EarnError, EarnKit, InputError, KitError, NetworkError, OnchainError, RateLimitError, RpcError, ServiceError, SwapChain, TOKEN_ALIASES, TransferSpeed, UnifiedBalanceChain, anyDepositParamsSchema, claimRewardsParamsSchema, createEarnKitContext, depositParamsSchema$1 as depositParamsSchema, claimRewards$1 as earnClaimRewards, deposit$3 as earnDeposit, exploreVaults$1 as earnExploreVaults, exploreVaultsIterator$1 as earnExploreVaultsIterator, getClaimRewardsQuote$1 as earnGetClaimRewardsQuote, getCrossChainDepositStatus$1 as earnGetCrossChainDepositStatus, getCrossChainDepositStatusOutcome as earnGetCrossChainDepositStatusOutcome, getDepositQuote$1 as earnGetDepositQuote, getPosition$1 as earnGetPosition, getSupportedChains$3 as earnGetSupportedChains, getVaults$1 as earnGetVaults, getWithdrawalQuote$1 as earnGetWithdrawalQuote, waitForCrossChainDeposit$1 as earnWaitForCrossChainDeposit, withdraw$1 as earnWithdraw, exploreVaultsIteratorParamsSchema, exploreVaultsParamsSchema, getClaimRewardsQuoteParamsSchema, getCrossChainDepositStatusParamsSchema, getDepositQuoteParamsSchema, getErrorCode, getErrorMessage, getPositionParamsSchema, getTokenDecimals, getVaultsParamsSchema, getWithdrawalQuoteParamsSchema, isBalanceError, isFatalError, isInputError, isKitError, isNetworkError, isOnchainError, isRateLimitError, isRetryableError$1 as isRetryableError, isRpcError, isServiceError, isTerminalCrossChainDepositStatus as isTerminalEarnCrossChainDepositStatus, isTokenAddress, isTokenAlias, isUserCancellationError, setExternalPrefix, validateToken, waitForCrossChainDepositParamsSchema, withdrawParamsSchema };
+export { AppKit, BalanceError, Blockchain, BridgeChain, EARN_EXECUTE_REVIEW_KIND, EarnChain, EarnError, EarnKit, InputError, KitError, NetworkError, OnchainError, RateLimitError, RpcError, ServiceError, SwapChain, TOKEN_ALIASES, TransferSpeed, UnifiedBalanceChain, anyDepositParamsSchema, claimRewardsParamsSchema, createEarnKitContext, depositParamsSchema$1 as depositParamsSchema, claimRewards$1 as earnClaimRewards, deposit$3 as earnDeposit, exploreVaults$1 as earnExploreVaults, exploreVaultsIterator$1 as earnExploreVaultsIterator, getClaimRewardsQuote$1 as earnGetClaimRewardsQuote, getCrossChainDepositStatus$1 as earnGetCrossChainDepositStatus, getCrossChainDepositStatusOutcome as earnGetCrossChainDepositStatusOutcome, getDepositQuote$1 as earnGetDepositQuote, getPosition$1 as earnGetPosition, getSupportedChains$3 as earnGetSupportedChains, getVaults$1 as earnGetVaults, getWithdrawalQuote$1 as earnGetWithdrawalQuote, waitForCrossChainDeposit$1 as earnWaitForCrossChainDeposit, withdraw$1 as earnWithdraw, exploreVaultsIteratorParamsSchema, exploreVaultsParamsSchema, getClaimRewardsQuoteParamsSchema, getCrossChainDepositStatusParamsSchema, getDepositQuoteParamsSchema, getErrorCode, getErrorMessage, getPositionParamsSchema, getTokenDecimals, getVaultsParamsSchema, getWithdrawalQuoteParamsSchema, isBalanceError, isEarnExecuteReview, isFatalError, isInputError, isKitError, isNetworkError, isOnchainError, isRateLimitError, isRetryableError$1 as isRetryableError, isRpcError, isServiceError, isTerminalCrossChainDepositStatus as isTerminalEarnCrossChainDepositStatus, isTokenAddress, isTokenAlias, isUserCancellationError, setExternalPrefix, validateToken, waitForCrossChainDepositParamsSchema, withdrawParamsSchema };
 //# sourceMappingURL=index.mjs.map