@circle-fin/adapter-ethers-v6 1.8.0 → 1.8.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @circle-fin/adapter-ethers-v6
 
+## 1.8.1
+
+### Patch Changes
+
+- Enable Earn deposit, withdrawal, and claim rewards execution when paired with `@circle-fin/earn-kit`.
+
 ## 1.8.0
 
 ### Minor Changes

package/index.cjs

@@ -408,6 +408,12 @@ const InputError = {
         name: 'INPUT_INVALID_AMOUNT',
         type: 'INPUT',
     },
+    /** Unsupported or invalid bridge route configuration */
+    UNSUPPORTED_ROUTE: {
+        code: 1003,
+        name: 'INPUT_UNSUPPORTED_ROUTE',
+        type: 'INPUT',
+    },
     /** Invalid or unsupported chain identifier */
     INVALID_CHAIN: {
         code: 1005,
@@ -564,6 +570,35 @@ const NetworkError = {
         type: 'NETWORK',
     }};
 
+/**
+ * Creates error for unsupported earn route.
+ *
+ * This error is thrown when no available earn provider supports the requested
+ * operation on the specified chain.
+ *
+ * @param operation - Earn operation name
+ * @param chain - Chain name where the earn operation was attempted
+ * @returns KitError with specific earn route details
+ *
+ * @example
+ * ```typescript
+ * import { createUnsupportedEarnRouteError } from '@core/errors'
+ *
+ * throw createUnsupportedEarnRouteError('deposit', 'Ethereum')
+ * // Message: "Earn deposit on Ethereum is not supported by any available provider."
+ * ```
+ */
+function createUnsupportedEarnRouteError(operation, chain) {
+    const errorDetails = {
+        ...InputError.UNSUPPORTED_ROUTE,
+        recoverability: 'FATAL',
+        message: `Earn ${operation} on ${chain} is not supported by any available provider.`,
+        cause: {
+            trace: { operation, chain },
+        },
+    };
+    return new KitError(errorDetails);
+}
 /**
  * Creates error for unsupported token on chain.
  *
@@ -2052,23 +2087,21 @@ var UnifiedBalanceChain;
  * Enumeration of blockchains that support earn (vault deposit/withdraw)
  * operations through the Earn Kit.
  *
- * Currently only Ethereum mainnet is supported. Additional chains
- * will be added as vault protocol support expands.
- *
  * @example
  * ```typescript
  * import { EarnChain } from '@core/chains'
  *
  * const result = await earnKit.deposit({
- *   from: { adapter, chain: EarnChain.Ethereum },
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
  *   vaultAddress: '0x...',
  *   amount: '100',
  * })
  * ```
  */
+// Values must match Blockchain enum members exactly.
 var EarnChain;
 (function (EarnChain) {
-    EarnChain["Ethereum"] = "Ethereum";
+    EarnChain["Arc_Testnet"] = "Arc_Testnet";
 })(EarnChain || (EarnChain = {}));
 
 /**
@@ -5762,7 +5795,7 @@ zod.z.union([
  * Zod schema for validating earn-specific chain identifiers.
  *
  * Validate that the provided chain is supported for earn (vault
- * deposit/withdraw) operations. Currently only Ethereum is
+ * deposit/withdraw) operations. Currently only Arc Testnet is
  * supported.
  *
  * Accept an EarnChain enum value, a matching string literal, or
@@ -5771,12 +5804,12 @@ zod.z.union([
  * @example
  * ```typescript
  * import { earnChainIdentifierSchema } from '@core/chains'
- * import { EarnChain, Ethereum } from '@core/chains'
+ * import { ArcTestnet, EarnChain } from '@core/chains'
  *
  * // Valid
- * earnChainIdentifierSchema.parse(EarnChain.Ethereum)
- * earnChainIdentifierSchema.parse('Ethereum')
- * earnChainIdentifierSchema.parse(Ethereum)
+ * earnChainIdentifierSchema.parse(EarnChain.Arc_Testnet)
+ * earnChainIdentifierSchema.parse('Arc_Testnet')
+ * earnChainIdentifierSchema.parse(ArcTestnet)
  *
  * // Invalid (throws ZodError)
  * earnChainIdentifierSchema.parse('Solana')
@@ -7389,7 +7422,9 @@ const hexStringSchema = zod.z
  * console.log(result.success) // true
  * ```
  */
-const evmAddressSchema = hexStringSchema.refine((value) => value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)');
+const evmAddressSchema = hexStringSchema
+    .refine((value) => value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)')
+    .transform((value) => value);
 /**
  * Schema for validating transaction hashes.
  *
@@ -7410,6 +7445,29 @@ const evmAddressSchema = hexStringSchema.refine((value) => value.length === 42,
  * ```
  */
 hexStringSchema.refine((value) => value.length === 66, 'Transaction hash must be exactly 66 characters long (0x + 64 hex characters)');
+/**
+ * Schema for validating EVM signatures.
+ *
+ * This schema validates that a string is a properly formatted 65-byte EVM
+ * signature:
+ * - Must be a valid hex string with '0x' prefix
+ * - Must be exactly 132 characters long (0x + 130 hex characters)
+ *
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { evmSignatureSchema } from '@core/adapter'
+ *
+ * const validSignature = `0x${'ab'.repeat(65)}`
+ *
+ * const result = evmSignatureSchema.safeParse(validSignature)
+ * console.log(result.success) // true
+ * ```
+ */
+const evmSignatureSchema = hexStringSchema
+    .refine((value) => value.length === 132, 'EVM signature must be exactly 132 characters long (0x + 130 hex characters)')
+    .transform((value) => value);
 /**
  * Schema for validating base58-encoded strings.
  *
@@ -7644,6 +7702,79 @@ function getSupportedChains(ecosystem) {
     }
 }
 
+/**
+ * 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',
+    },
+];
+
 /**
  * ERC20 ABI
  *
@@ -11009,78 +11140,6 @@ const bridgeContractAbi = [
     },
 ];
 
-/**
- * Adapter Contract ABI
- *
- * This ABI is used to interact with the Adapter smart contract that handles
- * gasless token approvals via permits and atomic swap execution.
- *
- * The execute() function is the primary entry point for swap operations.
- */
-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',
-    },
-];
-
 /**
  * ABI for the Circle Gateway Wallet contract.
  *
@@ -15502,6 +15561,107 @@ const balanceOf$2 = async (params, adapter, context) => {
     };
 };
 
+const hexBytesSchema = zod.z
+    .string()
+    .regex(/^0x([0-9a-fA-F]{2})*$/, {
+    message: 'value must be a 0x-prefixed even-length hex string',
+})
+    .transform((value) => value);
+const earnExecuteParamsSchema = zod.z
+    .object({
+    executeParams: zod.z.object({}).passthrough(),
+    signature: evmSignatureSchema,
+    tokenInputs: zod.z.array(zod.z.object({
+        permitType: zod.z.nativeEnum(PermitType),
+        token: evmAddressSchema,
+        amount: zod.z.bigint().refine((value) => value >= 0n, {
+            message: 'amount must be a non-negative bigint',
+        }),
+        permitCalldata: hexBytesSchema,
+    })),
+})
+    .passthrough();
+function validateAdapterContractAddress(chainName, value) {
+    const result = evmAddressSchema.safeParse(value);
+    if (!result.success) {
+        throw createValidationFailedError('chain.kitContracts.adapter', value, `Adapter contract for chain ${chainName} must be a 0x-prefixed 20-byte hex address.`);
+    }
+    return result.data;
+}
+function validateEarnExecuteParams(params) {
+    const result = earnExecuteParamsSchema.safeParse(params);
+    if (!result.success) {
+        throw createValidationErrorFromZod(result.error, 'earn execute params');
+    }
+    return {
+        executeParams: result.data.executeParams,
+        signature: result.data.signature,
+        tokenInputs: result.data.tokenInputs,
+        __isActionParams: true,
+    };
+}
+/**
+ * Prepare an earn operation against the adapter contract on EVM chains.
+ *
+ * Forward the service-signed `executeParams` and `signature` to the adapter
+ * contract's `execute` function. Token approvals are handled upstream by the
+ * provider (today via a separate `token.approve` transaction; future: permit
+ * entries in `tokenInputs`). This function performs runtime validation for
+ * plain-JS callers, prepares calldata only, performs no network I/O, and does
+ * not submit the transaction.
+ *
+ * @param params - Service-signed earn payload.
+ * @param adapter - EVM adapter used to prepare the transaction.
+ * @param context - Resolved operation context (chain + address).
+ * @returns Prepared chain request ready to `estimate()` or `execute()`.
+ * @throws {@link KitError} If the chain is not EVM-compatible.
+ * @throws {@link KitError} If the chain has no adapter contract configured.
+ * @throws {@link KitError} If required fields are missing or invalid.
+ *
+ * @example
+ * ```typescript
+ * const prepared = await evmAdapter.prepareAction(
+ *   'earn.deposit',
+ *   {
+ *     executeParams: {
+ *       instructions: [],
+ *       tokens: [],
+ *       execId: 1n,
+ *       deadline: 0n,
+ *       metadata: '0x',
+ *     },
+ *     tokenInputs: [],
+ *     signature: '0x...',
+ *   },
+ *   { chain, address },
+ * )
+ * const txHash = await prepared.execute()
+ * ```
+ */
+const prepareEarnExecute = async (params, adapter, context) => {
+    const { chain } = context;
+    if (chain.type !== 'evm') {
+        throw createInvalidChainError(chain.name, `Expected EVM chain, but received chain type: ${String(chain.type)}`);
+    }
+    const adapterContractAddress = chain.kitContracts?.adapter;
+    if (adapterContractAddress === undefined) {
+        throw createUnsupportedEarnRouteError('execute', chain.name);
+    }
+    const validatedAdapterAddress = validateAdapterContractAddress(chain.name, adapterContractAddress);
+    const validatedParams = validateEarnExecuteParams(params);
+    return adapter.prepare({
+        type: 'evm',
+        abi: adapterContractAbi,
+        address: validatedAdapterAddress,
+        functionName: 'execute',
+        args: [
+            validatedParams.executeParams,
+            validatedParams.tokenInputs,
+            validatedParams.signature,
+        ],
+    }, context);
+};
+
 /**
  * Type guard to check if params is ExecuteSwapEVMParams.
  *
@@ -16351,6 +16511,36 @@ const getHandlers = (adapter) => {
         'swap.execute': async (params, context) => {
             return executeSwap(params, adapter, context);
         },
+        /**
+         * Handler for earn deposit execution on EVM chains.
+         *
+         * Forwards the earn service's signed `executeParams` and `signature` to the
+         * on-chain adapter contract's `execute` function. Token approvals are handled
+         * by the earn provider via separate `token.approve` transactions.
+         */
+        'earn.deposit': async (params, context) => {
+            return prepareEarnExecute(params, adapter, context);
+        },
+        /**
+         * Handler for earn withdraw execution on EVM chains.
+         *
+         * Forwards the earn service's signed `executeParams` and `signature` to the
+         * on-chain adapter contract's `execute` function. Token approvals are handled
+         * by the earn provider via separate `token.approve` transactions.
+         */
+        'earn.withdraw': async (params, context) => {
+            return prepareEarnExecute(params, adapter, context);
+        },
+        /**
+         * Handler for earn claim rewards execution on EVM chains.
+         *
+         * Forwards the earn service's signed `executeParams` and `signature` to the
+         * on-chain adapter contract's `execute` function. Claim rewards does not
+         * require approvals because the adapter does not pull user tokens.
+         */
+        'earn.claimRewards': async (params, context) => {
+            return prepareEarnExecute(params, adapter, context);
+        },
         /**
          * Handler for CCTP v2 custom burn with hook operations on EVM chains.
          *

package/index.d.ts

@@ -1812,12 +1812,14 @@ declare enum PermitType {
  * The Adapter Contract uses this to pull tokens from the user's wallet
  * using permit signatures instead of requiring separate approval transactions.
  *
+ * Shared by the `swap.*` and `earn.*` action namespaces because both forward
+ * `tokenInputs` unchanged to the adapter contract's `execute` call.
+ *
  * @example
  * ```typescript
  * const tokenInput: TokenInput = {
  *   permitType: PermitType.EIP2612,
  *   token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
- *   from: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  *   amount: 1000000n, // 1 USDC
  *   permitCalldata: '0x...' // Encoded permit(value, deadline, v, r, s)
  * }
@@ -1840,12 +1842,91 @@ interface TokenInput {
      * ABI-encoded permit calldata.
      *
      * For EIP-2612: encode(value, deadline, v, r, s)
-     * For Permit2: encode(permit, signature)
      *
      * @example '0x0000000000000000000000000000000000000000000000000000000000989680...'
      */
     permitCalldata: `0x${string}`;
 }
+
+/**
+ * Parameters for executing a service-signed earn operation via the Adapter
+ * smart contract on EVM chains.
+ *
+ * Shared across earn action keys: `earn.deposit`, `earn.withdraw`, and
+ * `earn.claimRewards`. Each operation forwards the same `executeParams`,
+ * `tokenInputs`, and `signature` triple to the adapter contract's `execute`
+ * function. The service signs `executeParams` off-chain; the contract verifies
+ * the signature on-chain.
+ *
+ * @example
+ * ```typescript
+ * import type { ActionPayload } from '@core/adapter'
+ *
+ * const params: ActionPayload<'earn.deposit'> = {
+ *   executeParams: { instructions: [], tokens: [], execId: 1n, deadline: 0n, metadata: '0x' },
+ *   tokenInputs: [],
+ *   signature: '0x...',
+ * }
+ *
+ * const prepared = await adapter.prepareAction('earn.deposit', params, { chain, address })
+ * const txHash = await prepared.execute()
+ * ```
+ */
+interface ExecuteEarnEVMParams extends ActionParameters {
+    /**
+     * Execution parameters returned by the earn service.
+     *
+     * Kept as an opaque record so the adapter forwards the service-signed struct
+     * unchanged. The adapter contract ABI decodes it on-chain.
+     */
+    executeParams: Record<string, unknown>;
+    /**
+     * Token inputs with permit signatures for gasless approvals.
+     *
+     * Populated by the earn provider after it decides how token spending is
+     * authorised. Today deposit uses a separate `token.approve` transaction and
+     * passes `PermitType.NONE`; a future permit-enabled path can populate this
+     * field without a breaking change.
+     */
+    tokenInputs: TokenInput[];
+    /**
+     * EIP-712 signature from the earn service proxy.
+     *
+     * The adapter contract verifies this signature on-chain. Passed through
+     * unchanged.
+     */
+    signature: `0x${string}`;
+}
+/**
+ * Parameters for earn execute actions across supported ecosystems.
+ *
+ * EVM-only today; becomes a union when a non-EVM adapter implementation
+ * lands. Action handlers narrow via a property-based type guard, same
+ * pattern as {@link ExecuteSwapParams}.
+ */
+type ExecuteEarnParams = ExecuteEarnEVMParams;
+/**
+ * Action map for earn operations.
+ *
+ * Each action key forwards the same `(executeParams, tokenInputs, signature)`
+ * triple to the adapter contract. Provider-side orchestration performs any
+ * required token approval; this action only prepares the adapter execute call.
+ */
+interface EarnActionMap {
+    /**
+     * Execute a service-signed deposit against the adapter contract.
+     */
+    readonly deposit: ExecuteEarnParams;
+    /**
+     * Execute a service-signed withdraw against the adapter contract.
+     */
+    readonly withdraw: ExecuteEarnParams;
+    /**
+     * Execute a service-signed claim rewards against the adapter contract.
+     */
+    readonly claimRewards: ExecuteEarnParams;
+}
+
 /**
  * Single instruction to execute within the Adapter Contract.
  *
@@ -2027,7 +2108,6 @@ interface ExecuteParams {
  * const tokenInputs: TokenInput[] = [{
  *   permitType: PermitType.EIP2612,
  *   token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
- *   from: userAddress,
  *   amount: 1000000n,
  *   permitCalldata: '0x...' // Encoded permit signature
  * }]
@@ -2070,7 +2150,6 @@ interface ExecuteSwapEVMParams extends ActionParameters {
      * [{
      *   permitType: PermitType.EIP2612,
      *   token: '0xUSDC',
-     *   from: userAddress,
      *   amount: 1000000n,
      *   permitCalldata: '0x...'
      * }]
@@ -2806,6 +2885,8 @@ interface ActionMap {
     readonly usdt: USDTActionMap;
     /** Swap operations for DEX aggregator integrations. */
     readonly swap: SwapActionMap;
+    /** Earn operations that execute service-signed payloads via the adapter contract. */
+    readonly earn: EarnActionMap;
 }
 /**
  * Determine if a type represents an action parameter object (leaf node).

package/index.mjs

@@ -403,6 +403,12 @@ const InputError = {
         name: 'INPUT_INVALID_AMOUNT',
         type: 'INPUT',
     },
+    /** Unsupported or invalid bridge route configuration */
+    UNSUPPORTED_ROUTE: {
+        code: 1003,
+        name: 'INPUT_UNSUPPORTED_ROUTE',
+        type: 'INPUT',
+    },
     /** Invalid or unsupported chain identifier */
     INVALID_CHAIN: {
         code: 1005,
@@ -559,6 +565,35 @@ const NetworkError = {
         type: 'NETWORK',
     }};
 
+/**
+ * Creates error for unsupported earn route.
+ *
+ * This error is thrown when no available earn provider supports the requested
+ * operation on the specified chain.
+ *
+ * @param operation - Earn operation name
+ * @param chain - Chain name where the earn operation was attempted
+ * @returns KitError with specific earn route details
+ *
+ * @example
+ * ```typescript
+ * import { createUnsupportedEarnRouteError } from '@core/errors'
+ *
+ * throw createUnsupportedEarnRouteError('deposit', 'Ethereum')
+ * // Message: "Earn deposit on Ethereum is not supported by any available provider."
+ * ```
+ */
+function createUnsupportedEarnRouteError(operation, chain) {
+    const errorDetails = {
+        ...InputError.UNSUPPORTED_ROUTE,
+        recoverability: 'FATAL',
+        message: `Earn ${operation} on ${chain} is not supported by any available provider.`,
+        cause: {
+            trace: { operation, chain },
+        },
+    };
+    return new KitError(errorDetails);
+}
 /**
  * Creates error for unsupported token on chain.
  *
@@ -2047,23 +2082,21 @@ var UnifiedBalanceChain;
  * Enumeration of blockchains that support earn (vault deposit/withdraw)
  * operations through the Earn Kit.
  *
- * Currently only Ethereum mainnet is supported. Additional chains
- * will be added as vault protocol support expands.
- *
  * @example
  * ```typescript
  * import { EarnChain } from '@core/chains'
  *
  * const result = await earnKit.deposit({
- *   from: { adapter, chain: EarnChain.Ethereum },
+ *   from: { adapter, chain: EarnChain.Arc_Testnet },
  *   vaultAddress: '0x...',
  *   amount: '100',
  * })
  * ```
  */
+// Values must match Blockchain enum members exactly.
 var EarnChain;
 (function (EarnChain) {
-    EarnChain["Ethereum"] = "Ethereum";
+    EarnChain["Arc_Testnet"] = "Arc_Testnet";
 })(EarnChain || (EarnChain = {}));
 
 /**
@@ -5757,7 +5790,7 @@ z.union([
  * Zod schema for validating earn-specific chain identifiers.
  *
  * Validate that the provided chain is supported for earn (vault
- * deposit/withdraw) operations. Currently only Ethereum is
+ * deposit/withdraw) operations. Currently only Arc Testnet is
  * supported.
  *
  * Accept an EarnChain enum value, a matching string literal, or
@@ -5766,12 +5799,12 @@ z.union([
  * @example
  * ```typescript
  * import { earnChainIdentifierSchema } from '@core/chains'
- * import { EarnChain, Ethereum } from '@core/chains'
+ * import { ArcTestnet, EarnChain } from '@core/chains'
  *
  * // Valid
- * earnChainIdentifierSchema.parse(EarnChain.Ethereum)
- * earnChainIdentifierSchema.parse('Ethereum')
- * earnChainIdentifierSchema.parse(Ethereum)
+ * earnChainIdentifierSchema.parse(EarnChain.Arc_Testnet)
+ * earnChainIdentifierSchema.parse('Arc_Testnet')
+ * earnChainIdentifierSchema.parse(ArcTestnet)
  *
  * // Invalid (throws ZodError)
  * earnChainIdentifierSchema.parse('Solana')
@@ -7384,7 +7417,9 @@ const hexStringSchema = z
  * console.log(result.success) // true
  * ```
  */
-const evmAddressSchema = hexStringSchema.refine((value) => value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)');
+const evmAddressSchema = hexStringSchema
+    .refine((value) => value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)')
+    .transform((value) => value);
 /**
  * Schema for validating transaction hashes.
  *
@@ -7405,6 +7440,29 @@ const evmAddressSchema = hexStringSchema.refine((value) => value.length === 42,
  * ```
  */
 hexStringSchema.refine((value) => value.length === 66, 'Transaction hash must be exactly 66 characters long (0x + 64 hex characters)');
+/**
+ * Schema for validating EVM signatures.
+ *
+ * This schema validates that a string is a properly formatted 65-byte EVM
+ * signature:
+ * - Must be a valid hex string with '0x' prefix
+ * - Must be exactly 132 characters long (0x + 130 hex characters)
+ *
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { evmSignatureSchema } from '@core/adapter'
+ *
+ * const validSignature = `0x${'ab'.repeat(65)}`
+ *
+ * const result = evmSignatureSchema.safeParse(validSignature)
+ * console.log(result.success) // true
+ * ```
+ */
+const evmSignatureSchema = hexStringSchema
+    .refine((value) => value.length === 132, 'EVM signature must be exactly 132 characters long (0x + 130 hex characters)')
+    .transform((value) => value);
 /**
  * Schema for validating base58-encoded strings.
  *
@@ -7639,6 +7697,79 @@ function getSupportedChains(ecosystem) {
     }
 }
 
+/**
+ * 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',
+    },
+];
+
 /**
  * ERC20 ABI
  *
@@ -11004,78 +11135,6 @@ const bridgeContractAbi = [
     },
 ];
 
-/**
- * Adapter Contract ABI
- *
- * This ABI is used to interact with the Adapter smart contract that handles
- * gasless token approvals via permits and atomic swap execution.
- *
- * The execute() function is the primary entry point for swap operations.
- */
-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',
-    },
-];
-
 /**
  * ABI for the Circle Gateway Wallet contract.
  *
@@ -15497,6 +15556,107 @@ const balanceOf$2 = async (params, adapter, context) => {
     };
 };
 
+const hexBytesSchema = z
+    .string()
+    .regex(/^0x([0-9a-fA-F]{2})*$/, {
+    message: 'value must be a 0x-prefixed even-length hex string',
+})
+    .transform((value) => value);
+const earnExecuteParamsSchema = z
+    .object({
+    executeParams: z.object({}).passthrough(),
+    signature: evmSignatureSchema,
+    tokenInputs: z.array(z.object({
+        permitType: z.nativeEnum(PermitType),
+        token: evmAddressSchema,
+        amount: z.bigint().refine((value) => value >= 0n, {
+            message: 'amount must be a non-negative bigint',
+        }),
+        permitCalldata: hexBytesSchema,
+    })),
+})
+    .passthrough();
+function validateAdapterContractAddress(chainName, value) {
+    const result = evmAddressSchema.safeParse(value);
+    if (!result.success) {
+        throw createValidationFailedError('chain.kitContracts.adapter', value, `Adapter contract for chain ${chainName} must be a 0x-prefixed 20-byte hex address.`);
+    }
+    return result.data;
+}
+function validateEarnExecuteParams(params) {
+    const result = earnExecuteParamsSchema.safeParse(params);
+    if (!result.success) {
+        throw createValidationErrorFromZod(result.error, 'earn execute params');
+    }
+    return {
+        executeParams: result.data.executeParams,
+        signature: result.data.signature,
+        tokenInputs: result.data.tokenInputs,
+        __isActionParams: true,
+    };
+}
+/**
+ * Prepare an earn operation against the adapter contract on EVM chains.
+ *
+ * Forward the service-signed `executeParams` and `signature` to the adapter
+ * contract's `execute` function. Token approvals are handled upstream by the
+ * provider (today via a separate `token.approve` transaction; future: permit
+ * entries in `tokenInputs`). This function performs runtime validation for
+ * plain-JS callers, prepares calldata only, performs no network I/O, and does
+ * not submit the transaction.
+ *
+ * @param params - Service-signed earn payload.
+ * @param adapter - EVM adapter used to prepare the transaction.
+ * @param context - Resolved operation context (chain + address).
+ * @returns Prepared chain request ready to `estimate()` or `execute()`.
+ * @throws {@link KitError} If the chain is not EVM-compatible.
+ * @throws {@link KitError} If the chain has no adapter contract configured.
+ * @throws {@link KitError} If required fields are missing or invalid.
+ *
+ * @example
+ * ```typescript
+ * const prepared = await evmAdapter.prepareAction(
+ *   'earn.deposit',
+ *   {
+ *     executeParams: {
+ *       instructions: [],
+ *       tokens: [],
+ *       execId: 1n,
+ *       deadline: 0n,
+ *       metadata: '0x',
+ *     },
+ *     tokenInputs: [],
+ *     signature: '0x...',
+ *   },
+ *   { chain, address },
+ * )
+ * const txHash = await prepared.execute()
+ * ```
+ */
+const prepareEarnExecute = async (params, adapter, context) => {
+    const { chain } = context;
+    if (chain.type !== 'evm') {
+        throw createInvalidChainError(chain.name, `Expected EVM chain, but received chain type: ${String(chain.type)}`);
+    }
+    const adapterContractAddress = chain.kitContracts?.adapter;
+    if (adapterContractAddress === undefined) {
+        throw createUnsupportedEarnRouteError('execute', chain.name);
+    }
+    const validatedAdapterAddress = validateAdapterContractAddress(chain.name, adapterContractAddress);
+    const validatedParams = validateEarnExecuteParams(params);
+    return adapter.prepare({
+        type: 'evm',
+        abi: adapterContractAbi,
+        address: validatedAdapterAddress,
+        functionName: 'execute',
+        args: [
+            validatedParams.executeParams,
+            validatedParams.tokenInputs,
+            validatedParams.signature,
+        ],
+    }, context);
+};
+
 /**
  * Type guard to check if params is ExecuteSwapEVMParams.
  *
@@ -16346,6 +16506,36 @@ const getHandlers = (adapter) => {
         'swap.execute': async (params, context) => {
             return executeSwap(params, adapter, context);
         },
+        /**
+         * Handler for earn deposit execution on EVM chains.
+         *
+         * Forwards the earn service's signed `executeParams` and `signature` to the
+         * on-chain adapter contract's `execute` function. Token approvals are handled
+         * by the earn provider via separate `token.approve` transactions.
+         */
+        'earn.deposit': async (params, context) => {
+            return prepareEarnExecute(params, adapter, context);
+        },
+        /**
+         * Handler for earn withdraw execution on EVM chains.
+         *
+         * Forwards the earn service's signed `executeParams` and `signature` to the
+         * on-chain adapter contract's `execute` function. Token approvals are handled
+         * by the earn provider via separate `token.approve` transactions.
+         */
+        'earn.withdraw': async (params, context) => {
+            return prepareEarnExecute(params, adapter, context);
+        },
+        /**
+         * Handler for earn claim rewards execution on EVM chains.
+         *
+         * Forwards the earn service's signed `executeParams` and `signature` to the
+         * on-chain adapter contract's `execute` function. Claim rewards does not
+         * require approvals because the adapter does not pull user tokens.
+         */
+        'earn.claimRewards': async (params, context) => {
+            return prepareEarnExecute(params, adapter, context);
+        },
         /**
          * Handler for CCTP v2 custom burn with hook operations on EVM chains.
          *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circle-fin/adapter-ethers-v6",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "EVM blockchain adapter powered by Ethers v6",
   "keywords": [
     "circle",