@circle-fin/app-kit 1.11.0 → 1.12.0

package/earn.mjs

@@ -37,6 +37,7 @@ import 'bn.js';
 import '@coral-xyz/anchor';
 import 'bs58';
 import '@noble/curves/ed25519';
+import { decodeFunctionData } from 'viem';
 import { formatUnits as formatUnits$1 } from '@ethersproject/units';
 import { keccak256 } from '@ethersproject/keccak256';
 
@@ -677,6 +678,11 @@ class KitError extends Error {
         name: 'INPUT_INSUFFICIENT_SWAP_AMOUNT',
         type: 'INPUT'
     },
+    /** Action not supported by this adapter / ecosystem */ UNSUPPORTED_ACTION: {
+        code: 1008,
+        name: 'INPUT_UNSUPPORTED_ACTION',
+        type: 'INPUT'
+    },
     /** No route satisfies the slippage or minimum-output constraint */ SLIPPAGE_CONSTRAINT_NOT_MET: {
         code: 1009,
         name: 'INPUT_SLIPPAGE_CONSTRAINT_NOT_MET',
@@ -741,6 +747,29 @@ class KitError extends Error {
         type: 'LIQUIDITY'
     }
 };
+/**
+ * Standardized error definitions for RPC type errors.
+ *
+ * RPC errors occur when communicating with blockchain RPC providers,
+ * including endpoint failures, invalid responses, and provider-specific issues.
+ *
+ * @example
+ * ```typescript
+ * import { RpcError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...RpcError.ENDPOINT_ERROR,
+ *   recoverability: 'RETRYABLE',
+ *   message: 'RPC endpoint unavailable on Ethereum',
+ *   cause: { trace: { endpoint: 'https://mainnet.infura.io' } }
+ * })
+ * ```
+ */ const RpcError = {
+    /** RPC endpoint returned error or is unavailable */ ENDPOINT_ERROR: {
+        code: 4001,
+        name: 'RPC_ENDPOINT_ERROR',
+        type: 'RPC'
+    }};
 /**
  * Standardized error definitions for NETWORK type errors.
  *
@@ -2340,6 +2369,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 = {}));
@@ -2393,6 +2424,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";
@@ -2418,6 +2450,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) {
@@ -4955,7 +4988,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',
@@ -5820,6 +5854,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
@@ -5939,6 +6071,8 @@ var Chains = /*#__PURE__*/Object.freeze({
   WorldChainSepolia: WorldChainSepolia,
   XDC: XDC,
   XDCApothem: XDCApothem,
+  XLayer: XLayer,
+  XLayerTestnet: XLayerTestnet,
   ZKSyncEra: ZKSyncEra,
   ZKSyncEraSepolia: ZKSyncEraSepolia
 });
@@ -7382,6 +7516,7 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Unichain]: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
         [Blockchain.World_Chain]: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
         [Blockchain.XDC]: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
+        [Blockchain.X_Layer]: '0xB6CEceAB302E2E4948951eE7843FC24E92933061',
         [Blockchain.ZKSync_Era]: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
         // =========================================================================
         // Testnets (alphabetically sorted)
@@ -7416,6 +7551,7 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Unichain_Sepolia]: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
         [Blockchain.World_Chain_Sepolia]: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
         [Blockchain.XDC_Apothem]: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
+        [Blockchain.X_Layer_Testnet]: '0xDec90b78111Ba2fc6FC6d84d8B9ec159A2d4b9B3',
         [Blockchain.ZKSync_Sepolia]: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853'
     }
 };
@@ -8129,6 +8265,52 @@ const swapTokenEnumSchema = z.enum([
     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.
  *
@@ -8511,7 +8693,7 @@ const swapTokenEnumSchema = z.enum([
 }
 
 var name$3 = "@circle-fin/bridge-kit";
-var version$3 = "1.12.2";
+var version$3 = "1.13.0";
 var pkg$3 = {
 	name: name$3,
 	version: version$3};
@@ -8547,13 +8729,21 @@ var pkg$3 = {
     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.'
+        });
+    }
 });
 
 /**
@@ -9379,7 +9569,7 @@ var TransferSpeed;
 registerKit(`${pkg$3.name}/${pkg$3.version}`);
 
 var name$2 = "@circle-fin/swap-kit";
-var version$2 = "1.5.0";
+var version$2 = "1.5.1";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -10175,6 +10365,311 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     return apiKeyPattern.test(apiKey);
 };
 
+/**
+ * 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'
+    }
+];
+
+/**
+ * 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.
  *
@@ -12688,7 +13183,7 @@ new Set(Object.values(Blockchain));
 registerKit(`${pkg$2.name}/${pkg$2.version}`);
 
 var name$1 = "@circle-fin/earn-kit";
-var version$1 = "1.4.0";
+var version$1 = "1.5.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -13332,78 +13827,1010 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
 }
 
 /**
- * Prepare an earn adapter action, execute it, wait for confirmation, and
- * throw a structured revert error if the receipt status is `'reverted'`.
- *
- * Wraps the prepareAction, execute, waitForTransaction, and status check
- * sequence so the provider can dispatch any `earn.*` action key with
- * consistent revert handling.
- *
- * Gas estimation: after preparing the action the helper calls
- * {@link estimateBufferedGasLimit}, which applies a safety buffer to the
- * returned gas value. If estimation fails, execution falls through to the
- * adapter's default gas handling.
- *
- * @typeParam TActionKey - Earn action key being executed.
- * @param params - Adapter action, execution context, and revert message.
- * @returns The confirmed on-chain transaction hash and explorer URL.
- * @throws {@link KitError} If the transaction reverts on-chain.
- *
- * @example
- * ```typescript
- * const { txHash, explorerUrl } = await executeEarnAction({
- *   adapter,
- *   chain,
- *   address,
- *   actionKey: 'earn.deposit',
- *   actionParams: { executeParams, tokenInputs, signature },
- *   revertMessage: 'Earn deposit reverted on-chain',
- * })
- * ```
- *
- * @internal
- */ async function executeEarnAction(params) {
-    const { adapter, chain, address, actionKey, actionParams, revertMessage } = params;
-    const prepared = await adapter.prepareAction(actionKey, actionParams, {
-        chain,
-        address
-    });
-    const gasLimitOverride = await estimateBufferedGasLimit(prepared);
-    const txHash = prepared.type === 'evm' && gasLimitOverride !== undefined ? await prepared.execute({
-        gasLimit: gasLimitOverride
-    }) : await prepared.execute();
-    const explorerUrl = buildExplorerUrl(chain, txHash);
-    const receipt = await adapter.waitForTransaction(txHash, {
-        confirmations: 1
-    }, chain);
-    if (receipt.status === 'reverted') {
-        throw createTransactionRevertedError(chain.name, revertMessage, undefined, txHash, explorerUrl);
+ * 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 {
-        txHash,
-        explorerUrl,
-        ...receipt.gasUsed !== undefined && {
-            gasUsed: receipt.gasUsed
-        },
-        ...receipt.effectiveGasPrice !== undefined && {
-            effectiveGasPrice: receipt.effectiveGasPrice
+    return instructions.map((instruction, index)=>{
+        if (typeof instruction !== 'object' || instruction === null) {
+            throw decodeMismatchError(`instructions[${index.toString()}] is not an object`, {
+                index
+            });
         }
-    };
+        return instruction;
+    });
 }
-
 /**
- * Validate that a service-signed execution payload has not expired before
- * the SDK asks the wallet to broadcast a transaction.
+ * Build a fail-closed {@link KitError} for an earn decode or review failure.
  *
- * @internal
- */ function validateExecutionDeadline(executionParams) {
-    const deadline = BigInt(executionParams.deadline);
-    const now = BigInt(Math.floor(Date.now() / 1000));
-    if (deadline <= now) {
-        throw createValidationFailedError('executionParams.deadline', executionParams.deadline, 'Earn execution deadline has expired');
-    }
-}
-
+ * 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);
+}
+
+/**
+ * Prepare an earn adapter action, execute it, wait for confirmation, and
+ * throw a structured revert error if the receipt status is `'reverted'`.
+ *
+ * Wraps the prepareAction, execute, waitForTransaction, and status check
+ * sequence so the provider can dispatch any `earn.*` action key with
+ * consistent revert handling.
+ *
+ * Gas estimation: after preparing the action the helper calls
+ * {@link estimateBufferedGasLimit}, which applies a safety buffer to the
+ * returned gas value. If estimation fails, execution falls through to the
+ * adapter's default gas handling.
+ *
+ * @typeParam TActionKey - Earn action key being executed.
+ * @param params - Adapter action, execution context, and revert message.
+ * @returns The confirmed on-chain transaction hash and explorer URL.
+ * @throws {@link KitError} If the transaction reverts on-chain.
+ *
+ * @example
+ * ```typescript
+ * const { txHash, explorerUrl } = await executeEarnAction({
+ *   adapter,
+ *   chain,
+ *   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, 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({
+        gasLimit: gasLimitOverride
+    }) : await prepared.execute();
+    const explorerUrl = buildExplorerUrl(chain, txHash);
+    const receipt = await adapter.waitForTransaction(txHash, {
+        confirmations: 1
+    }, chain);
+    if (receipt.status === 'reverted') {
+        throw createTransactionRevertedError(chain.name, revertMessage, undefined, txHash, explorerUrl);
+    }
+    return {
+        txHash,
+        explorerUrl,
+        ...receipt.gasUsed !== undefined && {
+            gasUsed: receipt.gasUsed
+        },
+        ...receipt.effectiveGasPrice !== undefined && {
+            effectiveGasPrice: receipt.effectiveGasPrice
+        }
+    };
+}
+
+/**
+ * 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.
+ *
+ * @internal
+ */ function validateExecutionDeadline(executionParams) {
+    const deadline = BigInt(executionParams.deadline);
+    const now = BigInt(Math.floor(Date.now() / 1000));
+    if (deadline <= now) {
+        throw createValidationFailedError('executionParams.deadline', executionParams.deadline, 'Earn execution deadline has expired');
+    }
+}
+
 /** Base discriminators shared by every earn action payload. */ const EARN_ACTION_BASE = {
     protocol: 'earn',
     service: 'earn-service'
@@ -14687,7 +16114,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
 }
 
 var name = "@circle-fin/provider-earn-service";
-var version = "1.3.1";
+var version = "1.4.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -16315,6 +17742,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 {
@@ -16347,6 +17814,8 @@ function finishElapsedWait(lastStatus, lastError) {
                             tokenInputs,
                             signature
                         },
+                        action: 'deposit',
+                        executionParams,
                         revertMessage: 'Earn deposit reverted on-chain'
                     });
                     reportTransactionSuccess(transactionReportContext, 'Deposit', result);
@@ -16478,6 +17947,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 {
@@ -16510,6 +18017,8 @@ function finishElapsedWait(lastStatus, lastError) {
                             tokenInputs,
                             signature
                         },
+                        action: 'withdraw',
+                        executionParams,
                         revertMessage: 'Earn withdraw reverted on-chain'
                     });
                     reportTransactionSuccess(transactionReportContext, 'Withdraw', result);
@@ -16589,6 +18098,8 @@ function finishElapsedWait(lastStatus, lastError) {
                         tokenInputs: [],
                         signature
                     },
+                    action: 'claimRewards',
+                    executionParams,
                     revertMessage: 'Earn claim rewards reverted on-chain'
                 }), ({ txHash })=>txHash);
             return {
@@ -17272,11 +18783,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