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

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.
          *
@@ -17097,41 +17287,37 @@ function isBrowserWithEthereum() {
     return (typeof window !== 'undefined' && !!window.ethereum);
 }
 /**
- * Attempts to switch the connected chain in a browser wallet, or adds the chain if it is not recognized.
- *
- * @param signer - The current Ethers.js Signer instance, expected to be connected to a browser provider.
- * @param chain - The EVM chain definition to switch to.
- * @returns A promise resolving to the new Signer instance connected to the target chain.
- *
- * @remarks
- * This function uses the EIP-3326 `wallet_switchEthereumChain` and EIP-3085 `wallet_addEthereumChain` methods
- * to prompt the user to switch or add the specified chain in their browser wallet.
+ * Switch or add a chain via an EIP-1193 provider, then return a fresh signer.
  *
- * @throws {Error} If the provider does not support chain switching, or if the user rejects the request,
- * or if the operation fails for any other reason.
+ * @param provider - An EIP-1193 compatible provider with a `send` method.
+ * @param chain - The target EVM chain definition.
+ * @returns A promise resolving to a new Signer connected to the target chain.
+ * @throws When the user rejects the switch or the provider fails.
  */
-async function switchOrAddChainInBrowser(signer, chain) {
-    const win = window;
-    const signerWithProvider = signer;
-    if (!signerWithProvider?.provider?.send) {
-        throw new Error('Browser provider does not support chain switching');
-    }
+async function switchOrAddViaProvider(provider, chain) {
     try {
-        await signerWithProvider.provider.send('wallet_switchEthereumChain', [
+        await provider.send('wallet_switchEthereumChain', [
             { chainId: `0x${chain.chainId.toString(16)}` },
         ]);
-        return await getBrowserSigner(win);
     }
     catch (error) {
         if (typeof error === 'object' &&
             error !== null &&
             'code' in error &&
             error.code === UNRECOGNIZED_CHAIN_ID_ERROR_CODE) {
-            await addChainInBrowser(signerWithProvider, chain);
-            return await getBrowserSigner(win);
+            await addChainInBrowser({ provider }, chain);
+            await provider.send('wallet_switchEthereumChain', [
+                { chainId: `0x${chain.chainId.toString(16)}` },
+            ]);
+        }
+        else {
+            throw error;
         }
-        throw error;
     }
+    const browserProvider = provider instanceof BrowserProvider
+        ? provider
+        : new BrowserProvider(provider);
+    return await browserProvider.getSigner();
 }
 /**
  * Adds a new EVM chain to the user's browser wallet using the EIP-3085 `wallet_addEthereumChain` method.
@@ -17146,9 +17332,9 @@ async function switchOrAddChainInBrowser(signer, chain) {
  *
  * @throws {Error} If the provider does not support the `send` method or if the request fails.
  */
-async function addChainInBrowser(signerWithProvider, chain) {
+async function addChainInBrowser(providerLike, chain) {
     const rpcUrl = chain.rpcEndpoints[0];
-    await signerWithProvider.provider.send('wallet_addEthereumChain', [
+    await providerLike.provider.send('wallet_addEthereumChain', [
         {
             chainId: `0x${chain.chainId.toString(16)}`,
             chainName: chain.name,
@@ -17160,24 +17346,9 @@ async function addChainInBrowser(signerWithProvider, chain) {
         },
     ]);
 }
-/**
- * Returns a Signer instance from the browser's injected Ethereum provider.
- *
- * @param win - The browser window object with an injected `ethereum` provider.
- * @returns  A promise resolving Signer instance connected to the browser's provider.
- *
- * @remarks
- * This function wraps the Ethers.js `BrowserProvider` to obtain a Signer for user interaction.
- *
- * @throws {Error} If the `ethereum` provider is not available or if the signer cannot be retrieved.
- */
-async function getBrowserSigner(win) {
-    const browserProvider = new BrowserProvider(win.ethereum);
-    return await browserProvider.getSigner();
-}
 /**
  * Switches the chain for the given signer and returns a new signer for the target chain.
- * Handles both browser and server-side environments.
+ * Handles browser (injected + WalletConnect/Dynamic) and server-side environments.
  *
  * @param signer - The current signer instance
  * @param chain - The target chain definition
@@ -17185,8 +17356,21 @@ async function getBrowserSigner(win) {
  * @throws If switching fails or the environment is unsupported
  */
 async function switchChain(signer, chain) {
+    // Injected browser wallet (window.ethereum present)
     if (isBrowserWithEthereum()) {
-        return switchOrAddChainInBrowser(signer, chain);
+        const signerWithProvider = signer;
+        if (!signerWithProvider?.provider?.send) {
+            throw new Error('Browser provider does not support chain switching');
+        }
+        return switchOrAddViaProvider(signerWithProvider.provider, chain);
+    }
+    // Browser without window.ethereum (e.g., WalletConnect/Dynamic mobile wallets)
+    const signerWithProvider = signer;
+    const signerProvider = signerWithProvider.provider;
+    if (globalThis.window !== undefined &&
+        signerProvider &&
+        'send' in signerProvider) {
+        return switchOrAddViaProvider(signerProvider, chain);
     }
     // Server-side: recreate the provider and signer
     const rpcUrl = chain.rpcEndpoints[0];
@@ -18162,6 +18346,36 @@ class EthersAdapter extends EvmAdapter {
             });
         }
     }
+    /**
+     * Reads the on-chain bytecode for a given address via ethers' `getCode`.
+     *
+     * Returns the hex-encoded bytecode when the address is a contract, or
+     * `'0x'` when the address has no code (EOA). Used by Gateway burn-intent
+     * signing to detect smart-contract accounts, which are not supported by
+     * Gateway's ecrecover-based verification path.
+     */
+    async readBytecode(address, chain) {
+        const provider = await this.getProvider(chain);
+        try {
+            const code = await provider.getCode(address);
+            return code;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new KitError({
+                ...RpcError.ENDPOINT_ERROR,
+                recoverability: 'RETRYABLE',
+                message: `Failed to read bytecode for ${address}: ${errorMessage}`,
+                cause: {
+                    trace: {
+                        operation: 'readBytecode',
+                        address,
+                        chain: chain.name,
+                    },
+                },
+            });
+        }
+    }
     /**
      * Signs EIP-712 typed data using the configured signer with OperationContext.
      *

package/package.json

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