@circle-fin/adapter-ethers-v6 1.5.0 → 1.6.0

package/index.cjs

@@ -85,6 +85,10 @@ const ERROR_TYPES = {
     RPC: 'RPC',
     /** Internet connectivity, DNS resolution, connection issues */
     NETWORK: 'NETWORK',
+    /** API throttling, request frequency limits errors */
+    RATE_LIMIT: 'RATE_LIMIT',
+    /** Service errors */
+    SERVICE: 'SERVICE',
     /** Catch-all for unrecognized errors (code 0) */
     UNKNOWN: 'UNKNOWN',
 };
@@ -108,6 +112,8 @@ const ERROR_CODE_RANGES = [
     { min: 3000, max: 3999, type: 'NETWORK' },
     { min: 4000, max: 4999, type: 'RPC' },
     { min: 5000, max: 5999, type: 'ONCHAIN' },
+    { min: 7000, max: 7999, type: 'RATE_LIMIT' },
+    { min: 8000, max: 8999, type: 'SERVICE' },
     { min: 9000, max: 9999, type: 'BALANCE' },
 ];
 /** Special code for UNKNOWN errors */
@@ -155,6 +161,8 @@ const errorDetailsSchema = zod.z.object({
      * - 3000-3999: NETWORK errors - Connectivity issues
      * - 4000-4999: RPC errors - Provider issues, gas estimation
      * - 5000-5999: ONCHAIN errors - Transaction/simulation failures
+     * - 7000-7999: RATE_LIMIT errors - API throttling
+     * - 8000-8999: SERVICE errors - Internal service errors
      * - 9000-9999: BALANCE errors - Insufficient funds
      */
     code: zod.z
@@ -245,11 +253,11 @@ function validateErrorDetails(details) {
 const MAX_MESSAGE_LENGTH = 950;
 
 /**
- * Structured error class for Stablecoin Kit operations.
+ * Structured error class for App Kit operations.
  *
  * This class extends the native Error class while implementing the ErrorDetails
  * interface, providing a consistent error format for programmatic handling
- * across the Stablecoin Kits ecosystem. All properties are immutable to ensure
+ * across the App Kits ecosystem. All properties are immutable to ensure
  * error objects cannot be modified after creation.
  *
  * @example
@@ -259,6 +267,7 @@ const MAX_MESSAGE_LENGTH = 950;
  * const error = new KitError({
  *   code: 1001,
  *   name: 'INPUT_NETWORK_MISMATCH',
+ *   type: 'INPUT',
  *   recoverability: 'FATAL',
  *   message: 'Cannot bridge between mainnet and testnet'
  * })
@@ -276,7 +285,8 @@ const MAX_MESSAGE_LENGTH = 950;
  * // Error with cause information
  * const error = new KitError({
  *   code: 1002,
- *   name: 'INVALID_AMOUNT',
+ *   name: 'INPUT_INVALID_AMOUNT',
+ *   type: 'INPUT',
  *   recoverability: 'FATAL',
  *   message: 'Amount must be greater than zero',
  *   cause: {
@@ -360,6 +370,8 @@ class KitError extends Error {
  * - 3000-3999: NETWORK errors - Internet connectivity, DNS, connection issues
  * - 4000-4999: RPC errors - Blockchain provider issues, gas estimation, nonce errors
  * - 5000-5999: ONCHAIN errors - Transaction/simulation failures, gas exhaustion, reverts
+ * - 7000-7999: RATE_LIMIT errors - API throttling, request frequency limits
+ * - 8000-8999: SERVICE errors - Internal service errors, server failures
  * - 9000-9999: BALANCE errors - Insufficient funds, token balance, allowance
  */
 /**
@@ -390,19 +402,30 @@ class KitError extends Error {
  * ```
  */
 const InputError = {
+    /** Invalid amount format or value (negative, zero, or malformed) */
+    INVALID_AMOUNT: {
+        code: 1002,
+        name: 'INPUT_INVALID_AMOUNT',
+        type: 'INPUT',
+    },
     /** Invalid or unsupported chain identifier */
     INVALID_CHAIN: {
         code: 1005,
         name: 'INPUT_INVALID_CHAIN',
         type: 'INPUT',
     },
+    /** Unsupported token for chain */
+    UNSUPPORTED_TOKEN: {
+        code: 1006,
+        name: 'INPUT_UNSUPPORTED_TOKEN',
+        type: 'INPUT',
+    },
     /** General validation failure for complex validation rules */
     VALIDATION_FAILED: {
         code: 1098,
         name: 'INPUT_VALIDATION_FAILED',
         type: 'INPUT',
-    },
-};
+    }};
 /**
  * Standardized error definitions for BALANCE type errors.
  *
@@ -470,7 +493,20 @@ const OnchainError = {
         code: 5003,
         name: 'ONCHAIN_OUT_OF_GAS',
         type: 'ONCHAIN',
-    }};
+    },
+    /** Transaction size exceeds blockchain limit */
+    TRANSACTION_TOO_LARGE: {
+        code: 5005,
+        name: 'ONCHAIN_TRANSACTION_TOO_LARGE',
+        type: 'ONCHAIN',
+    },
+    /** Unknown blockchain error that cannot be categorized */
+    UNKNOWN_BLOCKCHAIN_ERROR: {
+        code: 5099,
+        name: 'ONCHAIN_UNKNOWN_BLOCKCHAIN_ERROR',
+        type: 'ONCHAIN',
+    },
+};
 /**
  * Standardized error definitions for RPC type errors.
  *
@@ -522,6 +558,66 @@ const NetworkError = {
         type: 'NETWORK',
     }};
 
+/**
+ * Creates error for unsupported token on chain.
+ *
+ * This error is thrown when a token is not supported on the specified chain.
+ *
+ * @param token - The token symbol (e.g., 'USDC', 'USDT')
+ * @param chain - The chain name where the token is unsupported
+ * @returns KitError with specific token support details
+ *
+ * @example
+ * ```typescript
+ * import { createUnsupportedTokenError } from '@core/errors'
+ *
+ * throw createUnsupportedTokenError('USDC', 'UnknownChain')
+ * // Message: "USDC is not supported on UnknownChain"
+ * ```
+ */
+function createUnsupportedTokenError(token, chain) {
+    const errorDetails = {
+        ...InputError.UNSUPPORTED_TOKEN,
+        recoverability: 'FATAL',
+        message: `${token} is not supported on ${chain}.`,
+        cause: {
+            trace: { token, chain },
+        },
+    };
+    return new KitError(errorDetails);
+}
+/**
+ * Creates error for invalid amount format or precision.
+ *
+ * This error is thrown when the provided amount doesn't meet validation
+ * requirements such as precision, range, or format.
+ *
+ * @param amount - The invalid amount string
+ * @param reason - Specific reason why amount is invalid
+ * @returns KitError with amount details and validation rule
+ *
+ * @example
+ * ```typescript
+ * import { createInvalidAmountError } from '@core/errors'
+ *
+ * throw createInvalidAmountError('0.000001', 'Amount must be at least 0.01 USDC')
+ * // Message: "Invalid amount '0.000001': Amount must be at least 0.01 USDC"
+ *
+ * throw createInvalidAmountError('1,000.50', 'Amount must be a numeric string with dot (.) as decimal separator, with no thousand separators or comma decimals')
+ * // Message: "Invalid amount '1,000.50': Amount must be a numeric string with dot (.) as decimal separator, with no thousand separators or comma decimals."
+ * ```
+ */
+function createInvalidAmountError(amount, reason) {
+    const errorDetails = {
+        ...InputError.INVALID_AMOUNT,
+        recoverability: 'FATAL',
+        message: `Invalid amount '${amount}': ${reason}.`,
+        cause: {
+            trace: { amount, reason },
+        },
+    };
+    return new KitError(errorDetails);
+}
 /**
  * Creates error for invalid chain configuration.
  *
@@ -544,7 +640,7 @@ function createInvalidChainError(chain, reason) {
     const errorDetails = {
         ...InputError.INVALID_CHAIN,
         recoverability: 'FATAL',
-        message: `Invalid chain '${chain}': ${reason}`,
+        message: `Invalid chain '${chain}': ${reason}.`,
         cause: {
             trace: { chain, reason },
         },
@@ -816,6 +912,8 @@ function createSimulationFailedError(chain, reason, trace) {
  * @param chain - The blockchain network where the transaction reverted
  * @param reason - The reason for the revert (e.g., revert message)
  * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
+ * @param txHash - The transaction hash if the transaction was submitted (optional)
+ * @param explorerUrl - The block explorer URL for the transaction (optional)
  * @returns KitError with transaction revert details
  *
  * @example
@@ -828,15 +926,17 @@ function createSimulationFailedError(chain, reason, trace) {
  *
  * @example
  * ```typescript
- * // With trace context for debugging
- * throw createTransactionRevertedError('Base', 'Slippage exceeded', {
- *   rawError: error,
- *   txHash: '0xabc...',
- *   blockNumber: '12345',
- * })
+ * // With trace context and transaction details for debugging
+ * throw createTransactionRevertedError(
+ *   'Base',
+ *   'Slippage exceeded',
+ *   { rawError: error },
+ *   '0x123...',
+ *   'https://basescan.org/tx/0x123...'
+ * )
  * ```
  */
-function createTransactionRevertedError(chain, reason, trace) {
+function createTransactionRevertedError(chain, reason, trace, txHash, explorerUrl) {
     return new KitError({
         ...OnchainError.TRANSACTION_REVERTED,
         recoverability: 'FATAL',
@@ -846,6 +946,8 @@ function createTransactionRevertedError(chain, reason, trace) {
                 ...trace,
                 chain,
                 reason,
+                ...(txHash !== undefined && txHash !== '' && { txHash }),
+                ...(explorerUrl !== undefined && explorerUrl !== '' && { explorerUrl }),
             },
         },
     });
@@ -858,6 +960,8 @@ function createTransactionRevertedError(chain, reason, trace) {
  *
  * @param chain - The blockchain network where the transaction ran out of gas
  * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
+ * @param txHash - The transaction hash if the transaction was submitted (optional)
+ * @param explorerUrl - The block explorer URL for the transaction (optional)
  * @returns KitError with out of gas details
  *
  * @example
@@ -872,13 +976,15 @@ function createTransactionRevertedError(chain, reason, trace) {
  * ```typescript
  * // With trace context for debugging
  * throw createOutOfGasError('Polygon', {
- *   rawError: error,
  *   gasUsed: '50000',
  *   gasLimit: '45000',
- * })
+ * },
+ *  '0xabc...',
+ *   'https://polygonscan.com/tx/0xabc...'
+ * )
  * ```
  */
-function createOutOfGasError(chain, trace) {
+function createOutOfGasError(chain, trace, txHash, explorerUrl) {
     return new KitError({
         ...OnchainError.OUT_OF_GAS,
         recoverability: 'FATAL',
@@ -887,20 +993,119 @@ function createOutOfGasError(chain, trace) {
             trace: {
                 ...trace,
                 chain,
+                ...(txHash !== undefined && txHash !== '' && { txHash }),
+                ...(explorerUrl !== undefined && explorerUrl !== '' && { explorerUrl }),
+            },
+        },
+    });
+}
+/**
+ * Creates error for transaction size exceeding blockchain limits.
+ *
+ * This error is thrown when a transaction's serialized size exceeds
+ * the blockchain's maximum transaction size limit. The error is FATAL
+ * as it requires reducing the transaction size (e.g., fewer instructions,
+ * smaller data payloads, or splitting into multiple transactions).
+ *
+ * Common on Solana where transactions have strict size limits (e.g., max 1232 bytes).
+ *
+ * @param chain - The blockchain network where the size limit was exceeded
+ * @param rawError - The original error from the underlying system (optional)
+ * @returns KitError with transaction size exceeded details
+ *
+ * @example
+ * ```typescript
+ * import { createTransactionTooLargeError } from '@core/errors'
+ *
+ * throw createTransactionTooLargeError('Solana')
+ * // Message: "Transaction size exceeds limit on Solana"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createTransactionTooLargeError } from '@core/errors'
+ *
+ * // With raw error containing size details
+ * throw createTransactionTooLargeError(
+ *   'Solana',
+ *   new Error('transaction too large: max: encoded/raw 1644/1232')
+ * )
+ * // Error includes size information in cause.trace
+ * ```
+ */
+function createTransactionTooLargeError(chain, rawError) {
+    return new KitError({
+        ...OnchainError.TRANSACTION_TOO_LARGE,
+        recoverability: 'FATAL',
+        message: `Transaction size exceeds limit on ${chain}`,
+        cause: {
+            trace: {
+                chain,
+                rawError,
+            },
+        },
+    });
+}
+/**
+ * Creates error for unknown blockchain errors that cannot be categorized.
+ *
+ * This error is used as a fallback when a blockchain error doesn't match
+ * any known patterns (balance, simulation, gas, network, RPC, etc.).
+ * The error is FATAL as we cannot determine if it's retriable without
+ * understanding the underlying cause.
+ *
+ * The original error message and context are preserved in the trace for
+ * debugging purposes.
+ *
+ * @param chain - The blockchain network where the error occurred
+ * @param originalMessage - The original error message from the blockchain
+ * @param rawError - The original error object from the underlying system (optional)
+ * @returns KitError with unknown blockchain error details
+ *
+ * @example
+ * ```typescript
+ * import { createUnknownBlockchainError } from '@core/errors'
+ *
+ * throw createUnknownBlockchainError('Ethereum', 'Unknown protocol error')
+ * // Message: "Unknown blockchain error on Ethereum: Unknown protocol error"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createUnknownBlockchainError } from '@core/errors'
+ *
+ * // With raw error for debugging
+ * const rawError = new Error('Unexpected blockchain state')
+ * throw createUnknownBlockchainError('Solana', rawError.message, rawError)
+ * // Error preserves full context in cause.trace
+ * ```
+ */
+function createUnknownBlockchainError(chain, originalMessage, rawError) {
+    const errorMessage = originalMessage
+        ? 'Unknown blockchain error on ' + chain + ': ' + originalMessage
+        : 'Unknown blockchain error on ' + chain;
+    return new KitError({
+        ...OnchainError.UNKNOWN_BLOCKCHAIN_ERROR,
+        recoverability: 'FATAL',
+        message: errorMessage,
+        cause: {
+            trace: {
+                chain,
+                rawError,
             },
         },
     });
 }
 
 /**
- * Creates error for RPC endpoint failures.
+ * Create error for RPC endpoint failures.
  *
- * This error is thrown when an RPC provider endpoint fails, returns an error,
+ * Throw when an RPC provider endpoint fails, returns an error,
  * or is unavailable. The error is RETRYABLE as RPC issues are often temporary.
  *
- * @param chain - The blockchain network where the RPC error occurred
- * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
- * @returns KitError with RPC endpoint error details
+ * @param chain - The blockchain network where the RPC error occurred.
+ * @param trace - Optional trace context (can include rawError and debugging data).
+ * @returns KitError with RPC endpoint error details.
  *
  * @example
  * ```typescript
@@ -912,7 +1117,6 @@ function createOutOfGasError(chain, trace) {
  *
  * @example
  * ```typescript
- * // With trace context for debugging
  * throw createRpcEndpointError('Ethereum', {
  *   rawError: error,
  *   endpoint: 'https://mainnet.infura.io/v3/...',
@@ -935,15 +1139,15 @@ function createRpcEndpointError(chain, trace) {
 }
 
 /**
- * Creates error for network connection failures.
+ * Create error for network connection failures.
  *
- * This error is thrown when network connectivity issues prevent reaching
+ * Throw when network connectivity issues prevent reaching
  * the blockchain network. The error is RETRYABLE as network issues are
  * often temporary.
  *
- * @param chain - The blockchain network where the connection failed
- * @param trace - Optional trace context to include in error (can include rawError and additional debugging data)
- * @returns KitError with network connection error details
+ * @param chain - The blockchain network where the connection failed.
+ * @param trace - Optional trace context (can include rawError and debugging data).
+ * @returns KitError with network connection error details.
  *
  * @example
  * ```typescript
@@ -955,7 +1159,6 @@ function createRpcEndpointError(chain, trace) {
  *
  * @example
  * ```typescript
- * // With trace context for debugging
  * throw createNetworkConnectionError('Ethereum', {
  *   rawError: error,
  *   endpoint: 'https://eth-mainnet.g.alchemy.com/v2/...',
@@ -977,6 +1180,25 @@ function createNetworkConnectionError(chain, trace) {
     });
 }
 
+/**
+ * Normalizes optional transaction details for error factories.
+ *
+ * Converts empty strings to undefined to ensure clean error traces.
+ *
+ * @param txHash - The transaction hash.
+ * @param explorerUrl - The explorer URL.
+ * @returns Normalized values or undefined.
+ */
+function normalizeTransactionDetails(txHash, explorerUrl) {
+    const normalized = {};
+    if (txHash !== undefined && txHash !== '') {
+        normalized.txHash = txHash;
+    }
+    if (explorerUrl !== undefined && explorerUrl !== '') {
+        normalized.explorerUrl = explorerUrl;
+    }
+    return normalized;
+}
 /**
  * Parses raw blockchain errors into structured KitError instances.
  *
@@ -984,12 +1206,17 @@ function createNetworkConnectionError(chain, trace) {
  * types and converts them into standardized KitError format. It handles
  * errors from viem, ethers, Solana web3.js, and other blockchain libraries.
  *
- * The parser recognizes 5 main error patterns:
+ * The parser recognizes 6 main error patterns:
  * 1. Insufficient balance errors
  * 2. Simulation/execution reverted errors
  * 3. Gas-related errors
  * 4. Network connectivity errors
  * 5. RPC provider errors
+ * 6. Transaction size limit errors
+ *
+ * When errors don't match known patterns, the parser uses operation context
+ * (e.g., 'simulation', 'estimateGas') to categorize them appropriately.
+ * Unrecognized errors without context are categorized as UNKNOWN_BLOCKCHAIN_ERROR.
  *
  * @param error - The raw error from the blockchain library
  * @param context - Context information including chain and optional token
@@ -1019,6 +1246,25 @@ function createNetworkConnectionError(chain, trace) {
  *   throw parseBlockchainError(error, { chain: 'Solana' })
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * // With transaction hash and explorer URL
+ * import { buildExplorerUrl } from '@core/utils'
+ * import { Ethereum } from '@core/chains'
+ *
+ * try {
+ *   const txHash = await walletClient.sendTransaction(...)
+ *   await waitForTransaction(txHash)
+ * } catch (error) {
+ *   const explorerUrl = buildExplorerUrl(Ethereum, txHash)
+ *   throw parseBlockchainError(error, {
+ *     chain: 'Ethereum',
+ *     txHash,
+ *     explorerUrl
+ *   })
+ * }
+ * ```
  */
 function parseBlockchainError(error, context) {
     const msg = extractMessage(error);
@@ -1033,7 +1279,7 @@ function parseBlockchainError(error, context) {
     // Pattern 2: Simulation and execution reverts
     // Matches contract revert errors and simulation failures
     if (/execution reverted|simulation failed|transaction reverted|transaction failed/i.test(msg)) {
-        const reason = extractRevertReason(msg) ?? 'Transaction reverted';
+        const reason = extractRevertReason(msg, error) ?? 'Transaction reverted';
         // Distinguish between simulation failures and transaction reverts
         // "simulation failed" or "eth_call" indicates pre-flight simulation
         // "transaction failed" or context.operation === 'transaction' indicates post-execution
@@ -1043,9 +1289,11 @@ function parseBlockchainError(error, context) {
             });
         }
         // Transaction execution failures or reverts
+        // Include txHash and explorerUrl if available (transaction was submitted)
+        const { txHash, explorerUrl } = normalizeTransactionDetails(context.txHash, context.explorerUrl);
         return createTransactionRevertedError(context.chain, reason, {
             rawError: error,
-        });
+        }, txHash, explorerUrl);
     }
     // Pattern 3: Gas-related errors
     // Matches gas estimation failures and gas exhaustion
@@ -1057,7 +1305,8 @@ function parseBlockchainError(error, context) {
     // Gas exhaustion errors
     // Use specific patterns without wildcards to avoid ReDoS
     if (/out of gas|gas limit exceeded|exceeds block gas limit/i.test(msg)) {
-        return createOutOfGasError(context.chain, { rawError: error });
+        const { txHash, explorerUrl } = normalizeTransactionDetails(context.txHash, context.explorerUrl);
+        return createOutOfGasError(context.chain, { rawError: error }, txHash, explorerUrl);
     }
     // Insufficient funds for gas
     if (/insufficient funds for gas/i.test(msg)) {
@@ -1073,15 +1322,38 @@ function parseBlockchainError(error, context) {
     if (/rpc|invalid response|rate limit|too many requests/i.test(msg)) {
         return createRpcEndpointError(context.chain, { rawError: error });
     }
+    // Pattern 6: Transaction size limit errors
+    // Matches transaction size errors from various blockchains:
+    // - Solana: "transaction too large: max: encoded/raw 1644/1232"
+    // - Generic: "transaction exceeds size limit", "max transaction size"
+    // Split into two checks to reduce regex complexity for SonarQube
+    const isSizeError = /transaction (?:too large|exceeds size limit|size exceeds)|encoded\/raw\s+\d+\/\d+|max transaction size/i.test(msg) || /(?:tx|transaction) size is too big:\s*\d+,\s*max:\s*\d+/i.test(msg);
+    if (isSizeError) {
+        return createTransactionTooLargeError(context.chain, error);
+    }
     // Fallback based on operation context
     // Gas-related operations are RPC calls
     if (context.operation === 'estimateGas' ||
         context.operation === 'getGasPrice') {
         return createRpcEndpointError(context.chain, { rawError: error });
     }
-    // Fallback for unrecognized errors
-    // Defaults to simulation failed as transaction execution is the most common failure point
-    return createSimulationFailedError(context.chain, msg.length > 0 ? msg : 'Unknown error', { rawError: error });
+    // Simulation operations that don't match standard patterns should still be
+    // categorized as simulation failures. This handles cases where blockchain
+    // libraries throw generic errors (e.g., "fail", "error") during staticCall
+    // operations without descriptive messages. The operation context is authoritative
+    // about what was being attempted, even when error messages are unclear.
+    //
+    // Example: ethers.js staticCall rejection with message "fail"
+    //   - Message doesn't match /execution reverted|simulation failed/
+    //   - But context.operation === 'simulation' tells us it was a simulation
+    //   - Result: SIMULATION_FAILED (accurate) vs UNKNOWN_BLOCKCHAIN_ERROR (misleading)
+    if (context.operation === 'simulation') {
+        return createSimulationFailedError(context.chain, msg.length > 0 ? msg : 'Simulation failed', { rawError: error });
+    }
+    // Final fallback for truly unrecognized errors
+    // Only errors that don't match any pattern AND lack operation context
+    // are categorized as unknown.
+    return createUnknownBlockchainError(context.chain, msg.length > 0 ? msg : 'Unknown error', { rawError: error });
 }
 /**
  * Type guard to check if error has Solana-Kit structure with logs.
@@ -1140,12 +1412,76 @@ function extractMessage(error) {
     return String(error);
 }
 /**
- * Extracts the revert reason from an error message.
+ * Mapping of custom error selectors to human-readable error names.
+ *
+ * These selectors correspond to custom errors from the contracts.
+ * When a transaction reverts with a custom error, the 4-byte selector
+ * (first 4 bytes of keccak256 of the error signature) is included in the error message.
+ *
+ */
+const CUSTOM_ERROR_SELECTORS = {
+    '0xd93c0665': 'This contract is currently paused', // EnforcedPause()
+    '0x3ee5aeb5': 'Security check failed due to a reentrancy attempt', // ReentrancyGuardReentrantCall()
+    '0x8baa579f': 'The provided signature is invalid or could not be verified', // InvalidSignature()
+    '0x1ab7da6b': 'This request has expired', // DeadlineExpired()
+    '0x64eee62e': 'No instructions provided', // EmptyInstructions()
+    '0x3c46992e': 'Too many execution steps were provided', // TooManyInstructions()
+    '0xe066e60e': 'Exceeds maximum token inputs limit', // TooManyTokenInputs()
+    '0x5566df5c': 'The beneficiary address is invalid', // InvalidBeneficiary()
+    '0xf41d7bc6': 'Execution ID already used', // ExecIdUsed()
+    '0x948726e2': 'The account balance does not meet the required minimum', // InvalidBalanceState()
+    '0x01aa0452': 'The permit type provided is not supported', // UnsupportedPermitType()
+    '0x13be252b': 'Token approval failed and the allowance is insufficient', // InsufficientAllowance()
+    '0x5274afe7': 'Token transfer or approval failed', // SafeERC20FailedOperation(address)
+    '0x00bc1dcb': 'One of the execution targets is invalid', // InvalidInstruction(uint256)
+    '0x5d693841': 'Cannot approve a zero address or a native token', // InvalidApprovalConfig(uint256)
+    '0x3ec5cfe1': 'Cannot validate output for a zero address token', // InvalidOutputConfig(uint256)
+    '0x492fd70e': 'Instruction call failed without revert data', // ExecutionFailed(uint256)
+    '0xba235e1a': 'The received token amount is lower than the minimum required', // InsufficientOutput(uint256,address,uint256,uint256)
+    '0x9147d463': 'Final balance is less than the initial balance', // InsufficientFinalBalance(address,uint256,uint256)
+    '0xf4b3b1bc': 'Native token transfer to the beneficiary failed', // NativeTransferFailed()
+};
+/**
+ * Attempts to extract an error selector from an error object or message.
+ *
+ * Checks multiple sources in priority order:
+ * 1. `error.data` field
+ * 2. Message pattern: "custom error 0x8baa579f"
+ *
+ * @param msg - The error message
+ * @param error - The error object (optional)
+ * @returns The 4 bytes selector , or undefined if not found
+ */
+function extractErrorSelector(msg, error) {
+    // Check error.data field
+    if (error !== null && typeof error === 'object' && 'data' in error) {
+        if (typeof error.data === 'string' && /^0x[0-9a-f]{8}$/i.test(error.data)) {
+            return error.data.toLowerCase();
+        }
+    }
+    // Check for "custom error 0x8baa579f" in the message
+    const match = /custom error (0x[0-9a-f]{8})\b/i.exec(msg);
+    const selector = match?.[1];
+    if (selector !== undefined && selector.length > 0) {
+        return selector.toLowerCase();
+    }
+    return undefined;
+}
+/**
+ * Extracts the revert reason from an error message and error object.
  *
  * Attempts to parse out the meaningful reason from execution revert errors,
  * removing common prefixes like "execution reverted:" or "reverted:".
+ * If the error contains a custom error selector, it will be resolved to its
+ * human-readable description with the selector included for developer reference.
+ *
+ * Supports multiple error formats:
+ * - Custom error with selector in `error.data` field (e.g., `{ data: "0x8baa579f", ... }`)
+ * - Message with selector pattern: `"Execution reverted with reason: custom error 0x8baa579f"`
+ * - Standard revert: `"execution reverted: Insufficient funds"`
  *
  * @param msg - The error message to extract from
+ * @param error - The full error object (optional, used to extract selector from `data` field)
  * @returns The extracted revert reason, or null if not found
  *
  * @example
@@ -1163,10 +1499,48 @@ function extractMessage(error) {
  * )
  * // Returns: 'Insufficient allowance'
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom error with selector in message
+ * const reason = extractRevertReason(
+ *   'Execution reverted with reason: custom error 0x8baa579f'
+ * )
+ * // Returns: 'The provided signature is invalid or could not be verified (0x8baa579f)'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error with data field
+ * const reason = extractRevertReason(
+ *   'execution reverted (unknown custom error)',
+ *   { data: '0x8baa579f' }
+ * )
+ * // Returns: 'The provided signature is invalid or could not be verified (0x8baa579f)'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Unrecognized selector preserved for debugging
+ * const reason = extractRevertReason(
+ *   'execution reverted (unknown custom error)',
+ *   { data: '0xdeadbeef' }
+ * )
+ * // Returns: 'Transaction reverted with error (0xdeadbeef)'
+ * ```
  */
-function extractRevertReason(msg) {
+function extractRevertReason(msg, error) {
+    // Try to extract and decode custom error selector
+    const selector = extractErrorSelector(msg, error);
+    if (selector !== undefined) {
+        const errorMessage = CUSTOM_ERROR_SELECTORS[selector];
+        if (errorMessage !== undefined) {
+            return `${errorMessage} (${selector})`;
+        }
+    }
     // Try to extract reason after "execution reverted:" or "reason:"
     // Use [^\n.]+ instead of .+? to avoid ReDoS vulnerability
+    // Fall back to standard revert reason extraction
     const patterns = [
         /(?:execution reverted|reverted):\s*([^\n.]+)/i,
         /reason:\s*([^\n.]+)/i,
@@ -1179,9 +1553,49 @@ function extractRevertReason(msg) {
             return extractedReason.trim();
         }
     }
+    // Preserve unrecognized selector so it appears in error output for debugging
+    if (selector !== undefined) {
+        return `Transaction reverted with error (${selector})`;
+    }
     return null;
 }
 
+/**
+ * Safely extracts error message from any error type.
+ *
+ * This utility handles different error types gracefully, extracting
+ * meaningful messages from Error instances, string errors, or providing
+ * a fallback for unknown error types. Never throws.
+ *
+ * @param error - Unknown error to extract message from
+ * @returns Error message string, or fallback message
+ *
+ * @example
+ * ```typescript
+ * import { getErrorMessage } from '@core/errors'
+ *
+ * try {
+ *   await riskyOperation()
+ * } catch (error) {
+ *   const message = getErrorMessage(error)
+ *   console.log('Error occurred:', message)
+ *   // Works with Error, KitError, string, or any other type
+ * }
+ * ```
+ */
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (typeof error === 'object' && error !== null && 'message' in error) {
+        return String(error.message);
+    }
+    return 'An unknown error occurred';
+}
+
 // -----------------------------------------------------------------------------
 // Blockchain Enum
 // -----------------------------------------------------------------------------
@@ -1257,6 +1671,122 @@ exports.Blockchain = void 0;
     Blockchain["ZKSync_Era"] = "ZKSync_Era";
     Blockchain["ZKSync_Sepolia"] = "ZKSync_Sepolia";
 })(exports.Blockchain || (exports.Blockchain = {}));
+/**
+ * Enum representing the subset of {@link Blockchain} that supports swap operations.
+ *
+ * This enum provides compile-time type safety for swap chain selection,
+ * ensuring only supported chains are available in IDE autocomplete
+ * when building swap parameters.
+ *
+ * @remarks
+ * Unlike the full {@link Blockchain} enum, SwapChain only includes networks
+ * where the swap functionality is actively supported by the library.
+ * Using this enum prevents runtime errors from attempting unsupported
+ * cross-chain swaps.
+ *
+ * Currently supports:
+ * - Ethereum mainnet
+ * - Base mainnet
+ * - Polygon mainnet
+ * - Solana mainnet
+ *
+ * @example
+ * ```typescript
+ * import { SwapChain, swap, createSwapKitContext } from '@circle-fin/swap-kit'
+ * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ *
+ * const context = createSwapKitContext()
+ * const adapter = createViemAdapterFromPrivateKey({
+ *   privateKey: process.env.PRIVATE_KEY
+ * })
+ *
+ * // ✅ Autocomplete shows only swap-supported chains
+ * const result = await swap(context, {
+ *   from: {
+ *     adapter,
+ *     chain: SwapChain.Ethereum // Autocomplete: Ethereum, Base, Polygon, Solana
+ *   },
+ *   tokenIn: 'USDC',
+ *   tokenOut: 'USDT',
+ *   amount: '100.0'
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // String literals also work (constrained to SwapChain values)
+ * const result = await swap(context, {
+ *   from: {
+ *     adapter,
+ *     chain: 'Ethereum' // ✅ Only SwapChain strings allowed
+ *   },
+ *   tokenIn: 'USDC',
+ *   tokenOut: 'NATIVE',
+ *   amount: '50.0'
+ * })
+ *
+ * // ❌ TypeScript error - Sui not in SwapChain enum
+ * const invalidResult = await swap(context, {
+ *   from: {
+ *     adapter,
+ *     chain: 'Sui' // Compile-time error!
+ *   },
+ *   tokenIn: 'USDC',
+ *   tokenOut: 'USDT',
+ *   amount: '100.0'
+ * })
+ * ```
+ */
+/**
+ * Enum representing chains that support same-chain swaps through the Swap Kit.
+ *
+ * Unlike the full {@link Blockchain} enum, SwapChain includes only mainnet
+ * networks where adapter contracts are deployed (CCTPv2 support).
+ *
+ * Dynamic validation via {@link isSwapSupportedChain} ensures chains
+ * automatically work when adapter contracts and supported tokens are deployed.
+ *
+ * @example
+ * ```typescript
+ * import { SwapChain } from '@core/chains'
+ * import { swap } from '@circle-fin/swap-kit'
+ *
+ * const result = await swap(context, {
+ *   from: {
+ *     adapter,
+ *     chain: SwapChain.Arbitrum  // Now supported!
+ *   },
+ *   tokenIn: 'USDC',
+ *   tokenOut: 'WETH',
+ *   amount: '100.0'
+ * })
+ * ```
+ *
+ * @see {@link isSwapSupportedChain} for runtime validation
+ * @see {@link getSwapSupportedChains} for all supported chains
+ */
+var SwapChain;
+(function (SwapChain) {
+    // Original 4 chains
+    SwapChain["Ethereum"] = "Ethereum";
+    SwapChain["Base"] = "Base";
+    SwapChain["Polygon"] = "Polygon";
+    SwapChain["Solana"] = "Solana";
+    // Additional supported chains
+    SwapChain["Arbitrum"] = "Arbitrum";
+    SwapChain["Optimism"] = "Optimism";
+    SwapChain["Avalanche"] = "Avalanche";
+    SwapChain["Linea"] = "Linea";
+    SwapChain["Ink"] = "Ink";
+    SwapChain["World_Chain"] = "World_Chain";
+    SwapChain["Unichain"] = "Unichain";
+    SwapChain["Plume"] = "Plume";
+    SwapChain["Sei"] = "Sei";
+    SwapChain["Sonic"] = "Sonic";
+    SwapChain["XDC"] = "XDC";
+    SwapChain["HyperEVM"] = "HyperEVM";
+    SwapChain["Monad"] = "Monad";
+})(SwapChain || (SwapChain = {}));
 // -----------------------------------------------------------------------------
 // Bridge Chain Enum (CCTPv2 Supported Chains)
 // -----------------------------------------------------------------------------
@@ -1408,6 +1938,7 @@ const Algorand = defineChain({
     rpcEndpoints: ['https://mainnet-api.algonode.cloud'],
     eurcAddress: null,
     usdcAddress: '31566704',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -1431,6 +1962,7 @@ const AlgorandTestnet = defineChain({
     rpcEndpoints: ['https://testnet-api.algonode.cloud'],
     eurcAddress: null,
     usdcAddress: '10458941',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -1454,6 +1986,7 @@ const Aptos = defineChain({
     rpcEndpoints: ['https://fullnode.mainnet.aptoslabs.com/v1'],
     eurcAddress: null,
     usdcAddress: '0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b',
+    usdtAddress: '0x357b0b74bc833e95a115ad22604854d6b0fca151cecd94111770e5d6ffc9dc2b',
     cctp: {
         domain: 9,
         contracts: {
@@ -1491,6 +2024,7 @@ const AptosTestnet = defineChain({
     rpcEndpoints: ['https://fullnode.testnet.aptoslabs.com/v1'],
     eurcAddress: null,
     usdcAddress: '0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832',
+    usdtAddress: null,
     cctp: {
         domain: 9,
         contracts: {
@@ -1508,6 +2042,121 @@ const AptosTestnet = defineChain({
     },
 });
 
+/**
+ * Complete swap token registry - single source of truth for all swap-supported tokens.
+ *
+ * @remarks
+ * All packages should import from this registry for swap operations.
+ * Adding a new swap token requires updating only this registry.
+ *
+ * The NATIVE token is handled separately as it resolves dynamically based on chain.
+ *
+ * @example
+ * ```typescript
+ * import { SWAP_TOKEN_REGISTRY } from '@core/chains'
+ *
+ * // Get token decimals
+ * const decimals = SWAP_TOKEN_REGISTRY.USDC.decimals  // 6
+ *
+ * // Check if token is stablecoin
+ * const isStable = SWAP_TOKEN_REGISTRY.DAI.category === 'stablecoin'  // true
+ * ```
+ */
+const SWAP_TOKEN_REGISTRY = {
+    // ============================================================================
+    // Stablecoins (6 decimals)
+    // ============================================================================
+    USDC: {
+        symbol: 'USDC',
+        decimals: 6,
+        category: 'stablecoin',
+        description: 'USD Coin',
+    },
+    EURC: {
+        symbol: 'EURC',
+        decimals: 6,
+        category: 'stablecoin',
+        description: 'Euro Coin',
+    },
+    USDT: {
+        symbol: 'USDT',
+        decimals: 6,
+        category: 'stablecoin',
+        description: 'Tether USD',
+    },
+    PYUSD: {
+        symbol: 'PYUSD',
+        decimals: 6,
+        category: 'stablecoin',
+        description: 'PayPal USD',
+    },
+    // ============================================================================
+    // Stablecoins (18 decimals)
+    // ============================================================================
+    DAI: {
+        symbol: 'DAI',
+        decimals: 18,
+        category: 'stablecoin',
+        description: 'MakerDAO stablecoin',
+    },
+    USDE: {
+        symbol: 'USDE',
+        decimals: 18,
+        category: 'stablecoin',
+        description: 'Ethena USD (synthetic dollar)',
+    },
+    // ============================================================================
+    // Wrapped Tokens
+    // ============================================================================
+    WBTC: {
+        symbol: 'WBTC',
+        decimals: 8,
+        category: 'wrapped',
+        description: 'Wrapped Bitcoin',
+    },
+    WETH: {
+        symbol: 'WETH',
+        decimals: 18,
+        category: 'wrapped',
+        description: 'Wrapped Ethereum',
+    },
+    WSOL: {
+        symbol: 'WSOL',
+        decimals: 9,
+        category: 'wrapped',
+        description: 'Wrapped Solana',
+    },
+    WAVAX: {
+        symbol: 'WAVAX',
+        decimals: 18,
+        category: 'wrapped',
+        description: 'Wrapped Avalanche',
+    },
+    WPOL: {
+        symbol: 'WPOL',
+        decimals: 18,
+        category: 'wrapped',
+        description: 'Wrapped Polygon',
+    },
+};
+/**
+ * Special NATIVE token constant for swap operations.
+ *
+ * @remarks
+ * NATIVE is handled separately from SWAP_TOKEN_REGISTRY because it resolves
+ * dynamically based on the chain (ETH on Ethereum, SOL on Solana, etc.).
+ * Its decimals are chain-specific.
+ */
+const NATIVE_TOKEN = 'NATIVE';
+/**
+ * Array of all supported swap token symbols including NATIVE.
+ * Useful for iteration, validation, and filtering.
+ */
+[
+    ...Object.keys(SWAP_TOKEN_REGISTRY),
+    NATIVE_TOKEN,
+];
+
 /**
  * The bridge contract address for EVM testnet networks.
  *
@@ -1524,6 +2173,13 @@ const BRIDGE_CONTRACT_EVM_TESTNET = '0xC5567a5E3370d4DBfB0540025078e283e36A363d'
  * USDC transfers on live networks.
  */
 const BRIDGE_CONTRACT_EVM_MAINNET = '0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0';
+/**
+ * The adapter contract address for EVM mainnet networks.
+ *
+ * This contract serves as an adapter for integrating with various protocols
+ * on EVM-compatible chains. Use this address for mainnet adapter integrations.
+ */
+const ADAPTER_CONTRACT_EVM_MAINNET = '0x7FB8c7260b63934d8da38aF902f87ae6e284a845';
 
 /**
  * Arc Testnet chain definition
@@ -1553,6 +2209,7 @@ const ArcTestnet = defineChain({
     rpcEndpoints: ['https://rpc.testnet.arc.network/'],
     eurcAddress: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
     usdcAddress: '0x3600000000000000000000000000000000000000',
+    usdtAddress: null,
     cctp: {
         domain: 26,
         contracts: {
@@ -1595,6 +2252,7 @@ const Arbitrum = defineChain({
     rpcEndpoints: ['https://arb1.arbitrum.io/rpc'],
     eurcAddress: null,
     usdcAddress: '0xaf88d065e77c8cc2239327c5edb3a432268e5831',
+    usdtAddress: null,
     cctp: {
         domain: 3,
         contracts: {
@@ -1619,6 +2277,7 @@ const Arbitrum = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -1643,6 +2302,7 @@ const ArbitrumSepolia = defineChain({
     rpcEndpoints: ['https://sepolia-rollup.arbitrum.io/rpc'],
     eurcAddress: null,
     usdcAddress: '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
+    usdtAddress: null,
     cctp: {
         domain: 3,
         contracts: {
@@ -1691,6 +2351,7 @@ const Avalanche = defineChain({
     rpcEndpoints: ['https://api.avax.network/ext/bc/C/rpc'],
     eurcAddress: '0xc891eb4cbdeff6e073e859e987815ed1505c2acd',
     usdcAddress: '0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E',
+    usdtAddress: '0x9702230a8ea53601f5cd2dc00fdbc13d4df4a8c7',
     cctp: {
         domain: 1,
         contracts: {
@@ -1715,6 +2376,7 @@ const Avalanche = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -1738,6 +2400,7 @@ const AvalancheFuji = defineChain({
     explorerUrl: 'https://subnets-test.avax.network/c-chain/tx/{hash}',
     eurcAddress: '0x5e44db7996c682e92a960b65ac713a54ad815c6b',
     usdcAddress: '0x5425890298aed601595a70ab815c96711a31bc65',
+    usdtAddress: null,
     cctp: {
         domain: 1,
         contracts: {
@@ -1787,6 +2450,7 @@ const Base = defineChain({
     rpcEndpoints: ['https://mainnet.base.org', 'https://base.publicnode.com'],
     eurcAddress: '0x60a3e35cc302bfa44cb288bc5a4f316fdb1adb42',
     usdcAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    usdtAddress: null,
     cctp: {
         domain: 6,
         contracts: {
@@ -1811,6 +2475,7 @@ const Base = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -1835,6 +2500,7 @@ const BaseSepolia = defineChain({
     rpcEndpoints: ['https://sepolia.base.org'],
     eurcAddress: '0x808456652fdb597867f38412077A9182bf77359F',
     usdcAddress: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+    usdtAddress: null,
     cctp: {
         domain: 6,
         contracts: {
@@ -1883,6 +2549,7 @@ const Celo = defineChain({
     rpcEndpoints: ['https://forno.celo.org'],
     eurcAddress: null,
     usdcAddress: '0xcebA9300f2b948710d2653dD7B07f33A8B32118C',
+    usdtAddress: '0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e',
     cctp: null,
 });
 
@@ -1907,6 +2574,7 @@ const CeloAlfajoresTestnet = defineChain({
     rpcEndpoints: ['https://alfajores-forno.celo-testnet.org'],
     eurcAddress: null,
     usdcAddress: '0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -1931,6 +2599,7 @@ const Codex = defineChain({
     rpcEndpoints: ['https://rpc.codex.xyz'],
     eurcAddress: null,
     usdcAddress: '0xd996633a415985DBd7D6D12f4A4343E31f5037cf',
+    usdtAddress: null,
     cctp: {
         domain: 12,
         contracts: {
@@ -1973,6 +2642,7 @@ const CodexTestnet = defineChain({
     rpcEndpoints: ['https://rpc.codex-stg.xyz'],
     eurcAddress: null,
     usdcAddress: '0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f',
+    usdtAddress: null,
     cctp: {
         domain: 12,
         contracts: {
@@ -2015,6 +2685,7 @@ const Ethereum = defineChain({
     rpcEndpoints: ['https://eth.merkle.io', 'https://ethereum.publicnode.com'],
     eurcAddress: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
     usdcAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+    usdtAddress: '0xdac17f958d2ee523a2206206994597c13d831ec7',
     cctp: {
         domain: 0,
         contracts: {
@@ -2039,6 +2710,7 @@ const Ethereum = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -2063,6 +2735,7 @@ const EthereumSepolia = defineChain({
     rpcEndpoints: ['https://sepolia.drpc.org'],
     eurcAddress: '0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4',
     usdcAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
+    usdtAddress: null,
     cctp: {
         domain: 0,
         contracts: {
@@ -2110,6 +2783,7 @@ const Hedera = defineChain({
     rpcEndpoints: ['https://mainnet.hashio.io/api'],
     eurcAddress: null,
     usdcAddress: '0.0.456858',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -2133,6 +2807,7 @@ const HederaTestnet = defineChain({
     rpcEndpoints: ['https://testnet.hashio.io/api'],
     eurcAddress: null,
     usdcAddress: '0.0.429274',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -2159,6 +2834,7 @@ const HyperEVM = defineChain({
     rpcEndpoints: ['https://rpc.hyperliquid.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
+    usdtAddress: null,
     cctp: {
         domain: 19,
         contracts: {
@@ -2177,6 +2853,7 @@ const HyperEVM = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -2202,6 +2879,7 @@ const HyperEVMTestnet = defineChain({
     rpcEndpoints: ['https://rpc.hyperliquid-testnet.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0x2B3370eE501B4a559b57D449569354196457D8Ab',
+    usdtAddress: null,
     cctp: {
         domain: 19,
         contracts: {
@@ -2249,6 +2927,7 @@ const Ink = defineChain({
     ],
     eurcAddress: null,
     usdcAddress: '0x2D270e6886d130D724215A266106e6832161EAEd',
+    usdtAddress: null,
     cctp: {
         domain: 21,
         contracts: {
@@ -2267,6 +2946,7 @@ const Ink = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -2295,6 +2975,7 @@ const InkTestnet = defineChain({
     ],
     eurcAddress: null,
     usdcAddress: '0xFabab97dCE620294D2B0b0e46C68964e326300Ac',
+    usdtAddress: null,
     cctp: {
         domain: 21,
         contracts: {
@@ -2337,6 +3018,7 @@ const Linea = defineChain({
     rpcEndpoints: ['https://rpc.linea.build'],
     eurcAddress: null,
     usdcAddress: '0x176211869ca2b568f2a7d4ee941e073a821ee1ff',
+    usdtAddress: null,
     cctp: {
         domain: 11,
         contracts: {
@@ -2355,6 +3037,7 @@ const Linea = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -2379,6 +3062,7 @@ const LineaSepolia = defineChain({
     rpcEndpoints: ['https://rpc.sepolia.linea.build'],
     eurcAddress: null,
     usdcAddress: '0xfece4462d57bd51a6a552365a011b95f0e16d9b7',
+    usdtAddress: null,
     cctp: {
         domain: 11,
         contracts: {
@@ -2423,6 +3107,7 @@ const Monad = defineChain({
     rpcEndpoints: ['https://rpc.monad.xyz'],
     eurcAddress: null,
     usdcAddress: '0x754704Bc059F8C67012fEd69BC8A327a5aafb603',
+    usdtAddress: null,
     cctp: {
         domain: 15,
         contracts: {
@@ -2441,6 +3126,7 @@ const Monad = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -2467,6 +3153,7 @@ const MonadTestnet = defineChain({
     rpcEndpoints: ['https://testnet-rpc.monad.xyz'],
     eurcAddress: null,
     usdcAddress: '0x534b2f3A21130d7a60830c2Df862319e593943A3',
+    usdtAddress: null,
     cctp: {
         domain: 15,
         contracts: {
@@ -2508,6 +3195,7 @@ const NEAR = defineChain({
     rpcEndpoints: ['https://eth-rpc.mainnet.near.org'],
     eurcAddress: null,
     usdcAddress: '17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1',
+    usdtAddress: 'usdt.tether-token.near',
     cctp: null,
 });
 
@@ -2531,6 +3219,7 @@ const NEARTestnet = defineChain({
     rpcEndpoints: ['https://eth-rpc.testnet.near.org'],
     eurcAddress: null,
     usdcAddress: '3e2210e1184b45b64c8a434c0a7e7b23cc04ea7eb7a6c3c32520d03d4afcb8af',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -2554,6 +3243,7 @@ const Noble = defineChain({
     rpcEndpoints: ['https://noble-rpc.polkachu.com'],
     eurcAddress: null,
     usdcAddress: 'uusdc',
+    usdtAddress: null,
     cctp: {
         domain: 4,
         contracts: {
@@ -2590,6 +3280,7 @@ const NobleTestnet = defineChain({
     rpcEndpoints: ['https://noble-testnet-rpc.polkachu.com'],
     eurcAddress: null,
     usdcAddress: 'uusdc',
+    usdtAddress: null,
     cctp: {
         domain: 4,
         contracts: {
@@ -2627,6 +3318,7 @@ const Optimism = defineChain({
     rpcEndpoints: ['https://mainnet.optimism.io'],
     eurcAddress: null,
     usdcAddress: '0x0b2c639c533813f4aa9d7837caf62653d097ff85',
+    usdtAddress: null,
     cctp: {
         domain: 2,
         contracts: {
@@ -2651,6 +3343,7 @@ const Optimism = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -2675,6 +3368,7 @@ const OptimismSepolia = defineChain({
     rpcEndpoints: ['https://sepolia.optimism.io'],
     eurcAddress: null,
     usdcAddress: '0x5fd84259d66Cd46123540766Be93DFE6D43130D7',
+    usdtAddress: null,
     cctp: {
         domain: 2,
         contracts: {
@@ -2725,6 +3419,7 @@ const Plume = defineChain({
     rpcEndpoints: ['https://rpc.plume.org'],
     eurcAddress: null,
     usdcAddress: '0x222365EF19F7947e5484218551B56bb3965Aa7aF',
+    usdtAddress: null,
     cctp: {
         domain: 22,
         contracts: {
@@ -2743,6 +3438,7 @@ const Plume = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -2768,6 +3464,7 @@ const PlumeTestnet = defineChain({
     rpcEndpoints: ['https://testnet-rpc.plume.org'],
     eurcAddress: null,
     usdcAddress: '0xcB5f30e335672893c7eb944B374c196392C19D18',
+    usdtAddress: null,
     cctp: {
         domain: 22,
         contracts: {
@@ -2809,6 +3506,7 @@ const PolkadotAssetHub = defineChain({
     rpcEndpoints: ['https://asset-hub-polkadot-rpc.n.dwellir.com'],
     eurcAddress: null,
     usdcAddress: '1337',
+    usdtAddress: '1984',
     cctp: null,
 });
 
@@ -2832,6 +3530,7 @@ const PolkadotWestmint = defineChain({
     rpcEndpoints: ['https://westmint-rpc.polkadot.io'],
     eurcAddress: null,
     usdcAddress: 'Asset ID 31337',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -2853,9 +3552,10 @@ const Polygon = defineChain({
     chainId: 137,
     isTestnet: false,
     explorerUrl: 'https://polygonscan.com/tx/{hash}',
-    rpcEndpoints: ['https://polygon-rpc.com', 'https://polygon.publicnode.com'],
+    rpcEndpoints: ['https://polygon.publicnode.com', 'https://polygon.drpc.org'],
     eurcAddress: null,
     usdcAddress: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359',
+    usdtAddress: null,
     cctp: {
         domain: 7,
         contracts: {
@@ -2880,6 +3580,7 @@ const Polygon = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -2904,6 +3605,7 @@ const PolygonAmoy = defineChain({
     rpcEndpoints: ['https://rpc-amoy.polygon.technology'],
     eurcAddress: null,
     usdcAddress: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
+    usdtAddress: null,
     cctp: {
         domain: 7,
         contracts: {
@@ -2954,6 +3656,7 @@ const Sei = defineChain({
     rpcEndpoints: ['https://evm-rpc.sei-apis.com'],
     eurcAddress: null,
     usdcAddress: '0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392',
+    usdtAddress: null,
     cctp: {
         domain: 16,
         contracts: {
@@ -2972,6 +3675,7 @@ const Sei = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -2997,6 +3701,7 @@ const SeiTestnet = defineChain({
     rpcEndpoints: ['https://evm-rpc-testnet.sei-apis.com'],
     eurcAddress: null,
     usdcAddress: '0x4fCF1784B31630811181f670Aea7A7bEF803eaED',
+    usdtAddress: null,
     cctp: {
         domain: 16,
         contracts: {
@@ -3039,6 +3744,7 @@ const Sonic = defineChain({
     rpcEndpoints: ['https://rpc.soniclabs.com'],
     eurcAddress: null,
     usdcAddress: '0x29219dd400f2Bf60E5a23d13Be72B486D4038894',
+    usdtAddress: null,
     cctp: {
         domain: 13,
         contracts: {
@@ -3057,6 +3763,7 @@ const Sonic = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -3081,6 +3788,7 @@ const SonicTestnet = defineChain({
     rpcEndpoints: ['https://rpc.testnet.soniclabs.com'],
     eurcAddress: null,
     usdcAddress: '0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51',
+    usdtAddress: null,
     cctp: {
         domain: 13,
         contracts: {
@@ -3122,6 +3830,7 @@ const Solana = defineChain({
     rpcEndpoints: ['https://api.mainnet-beta.solana.com'],
     eurcAddress: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
     usdcAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+    usdtAddress: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
     cctp: {
         domain: 5,
         contracts: {
@@ -3168,6 +3877,7 @@ const SolanaDevnet = defineChain({
     explorerUrl: 'https://solscan.io/tx/{hash}?cluster=devnet',
     eurcAddress: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
     usdcAddress: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU',
+    usdtAddress: null,
     cctp: {
         domain: 5,
         contracts: {
@@ -3216,6 +3926,7 @@ const Stellar = defineChain({
     rpcEndpoints: ['https://horizon.stellar.org'],
     eurcAddress: 'EURC-GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2',
     usdcAddress: 'USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -3239,6 +3950,7 @@ const StellarTestnet = defineChain({
     rpcEndpoints: ['https://horizon-testnet.stellar.org'],
     eurcAddress: 'EURC-GB3Q6QDZYTHWT7E5PVS3W7FUT5GVAFC5KSZFFLPU25GO7VTC3NM2ZTVO',
     usdcAddress: 'USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -3262,6 +3974,7 @@ const Sui = defineChain({
     rpcEndpoints: ['https://fullnode.mainnet.sui.io'],
     eurcAddress: null,
     usdcAddress: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
+    usdtAddress: null,
     cctp: {
         domain: 8,
         contracts: {
@@ -3299,6 +4012,7 @@ const SuiTestnet = defineChain({
     rpcEndpoints: ['https://fullnode.testnet.sui.io'],
     eurcAddress: null,
     usdcAddress: '0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC',
+    usdtAddress: null,
     cctp: {
         domain: 8,
         contracts: {
@@ -3337,6 +4051,7 @@ const Unichain = defineChain({
     rpcEndpoints: ['https://mainnet.unichain.org'],
     eurcAddress: null,
     usdcAddress: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
+    usdtAddress: null,
     cctp: {
         domain: 10,
         contracts: {
@@ -3361,6 +4076,7 @@ const Unichain = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -3385,6 +4101,7 @@ const UnichainSepolia = defineChain({
     rpcEndpoints: ['https://sepolia.unichain.org'],
     eurcAddress: null,
     usdcAddress: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
+    usdtAddress: null,
     cctp: {
         domain: 10,
         contracts: {
@@ -3433,6 +4150,7 @@ const WorldChain = defineChain({
     rpcEndpoints: ['https://worldchain-mainnet.g.alchemy.com/public'],
     eurcAddress: null,
     usdcAddress: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
+    usdtAddress: null,
     cctp: {
         domain: 14,
         contracts: {
@@ -3451,6 +4169,7 @@ const WorldChain = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -3478,6 +4197,7 @@ const WorldChainSepolia = defineChain({
     ],
     eurcAddress: null,
     usdcAddress: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
+    usdtAddress: null,
     cctp: {
         domain: 14,
         contracts: {
@@ -3522,6 +4242,7 @@ const XDC = defineChain({
     rpcEndpoints: ['https://erpc.xdcrpc.com', 'https://erpc.xinfin.network'],
     eurcAddress: null,
     usdcAddress: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
+    usdtAddress: null,
     cctp: {
         domain: 18,
         contracts: {
@@ -3540,6 +4261,7 @@ const XDC = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
 });
 
@@ -3564,6 +4286,7 @@ const XDCApothem = defineChain({
     rpcEndpoints: ['https://erpc.apothem.network'],
     eurcAddress: null,
     usdcAddress: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
+    usdtAddress: null,
     cctp: {
         domain: 18,
         contracts: {
@@ -3606,6 +4329,7 @@ const ZKSyncEra = defineChain({
     rpcEndpoints: ['https://mainnet.era.zksync.io'],
     eurcAddress: null,
     usdcAddress: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -3630,6 +4354,7 @@ const ZKSyncEraSepolia = defineChain({
     rpcEndpoints: ['https://sepolia.era.zksync.dev'],
     eurcAddress: null,
     usdcAddress: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853',
+    usdtAddress: null,
     cctp: null,
 });
 
@@ -3775,10 +4500,12 @@ const baseChainDefinitionSchema = zod.z.object({
     rpcEndpoints: zod.z.array(zod.z.string()),
     eurcAddress: zod.z.string().nullable(),
     usdcAddress: zod.z.string().nullable(),
+    usdtAddress: zod.z.string().nullable(),
     cctp: zod.z.any().nullable(), // We'll accept any CCTP config structure
     kitContracts: zod.z
         .object({
         bridge: zod.z.string().optional(),
+        adapter: zod.z.string().optional(),
     })
         .optional(),
 });
@@ -3893,6 +4620,29 @@ zod.z.union([
     zod.z.nativeEnum(exports.Blockchain),
     chainDefinitionSchema$1,
 ]);
+/**
+ * Zod schema for validating swap-specific chain identifiers.
+ *
+ * Validates chains based on:
+ * - CCTPv2 support (adapter contract deployed)
+ * - Mainnet only (no testnets)
+ * - At least one supported token available
+ *
+ */
+zod.z.union([
+    // String blockchain identifier (accepts SwapChain enum values)
+    zod.z.string().refine((val) => val in SwapChain, (val) => ({
+        message: `"${val}" is not a supported swap chain. ` +
+            `Supported chains: ${Object.values(SwapChain).join(', ')}`,
+    })),
+    // SwapChain enum
+    zod.z.nativeEnum(SwapChain),
+    // ChainDefinition object (checks if chain.chain is in SwapChain)
+    chainDefinitionSchema$1.refine((chain) => chain.chain in SwapChain, (chain) => ({
+        message: `"${chain.chain}" is not a supported swap chain. ` +
+            `Supported chains: ${Object.values(SwapChain).join(', ')}`,
+    })),
+]);
 /**
  * Zod schema for validating bridge chain identifiers.
  *
@@ -3932,12 +4682,44 @@ zod.z.union([
     })),
 ]);
 
+/**
+ * @packageDocumentation
+ * @module SwapTokenSchemas
+ *
+ * Zod validation schemas for supported swap tokens.
+ */
+// Internal enum used after input normalization.
+const swapTokenEnumSchema = zod.z.enum([
+    ...Object.keys(SWAP_TOKEN_REGISTRY),
+    NATIVE_TOKEN,
+]);
+/**
+ * Zod schema for validating supported swap token symbols.
+ *
+ * Accepts any token symbol from the SWAP_TOKEN_REGISTRY plus NATIVE.
+ * Input matching is case-insensitive and normalized to uppercase.
+ *
+ * @example
+ * ```typescript
+ * import { supportedSwapTokenSchema } from '@core/chains'
+ *
+ * const result = supportedSwapTokenSchema.safeParse('USDC')
+ * if (result.success) {
+ *   console.log('Valid swap token:', result.data)
+ * }
+ * ```
+ */
+zod.z
+    .string()
+    .transform((value) => value.toUpperCase())
+    .pipe(swapTokenEnumSchema);
+
 /**
  * Get all supported EVM chain definitions.
  *
  * This function searches through all available blockchain definitions and returns
  * only those that are EVM-compatible. It provides a comprehensive list of all
- * EVM chains supported by the Stablecoin Kits ecosystem.
+ * EVM chains supported by the App Kits ecosystem.
  *
  * @returns Array of all EVM chain definitions supported by the library
  *
@@ -4031,6 +4813,11 @@ const getChainByEnum = (blockchain) => {
  * ```
  */
 function resolveChainIdentifier(chainIdentifier) {
+    // Handle null explicitly (typeof null === 'object' in JavaScript)
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (chainIdentifier === null) {
+        throw new Error(`Invalid chain identifier type: null. Expected ChainDefinition object, Blockchain enum, or string literal.`);
+    }
     // If it's already a ChainDefinition object, return it unchanged
     if (typeof chainIdentifier === 'object') {
         return chainIdentifier;
@@ -4393,11 +5180,11 @@ async function resolveOperationContext(adapter, ctx) {
 /**
  * Abstract class defining the standard interface for an adapter that interacts with a specific blockchain.
  *
- * A `Adapter` is responsible for encapsulating chain-specific logic necessary to
+ * An `Adapter` is responsible for encapsulating chain-specific logic necessary to
  * perform operations like sending transactions, querying balances, or interacting with smart contracts.
  * Implementations of this class will provide concrete logic for a particular blockchain protocol.
  *
- * This abstraction allows the Stablecoin Kits to work with multiple blockchains in a uniform way.
+ * This abstraction allows the App Kit to work with multiple blockchains in a uniform way.
  *
  * @typeParam TAdapterCapabilities - The adapter capabilities type for compile-time address validation.
  * When provided, enables strict typing of operation context based on the adapter's address control model.
@@ -4921,6 +5708,435 @@ const convertAddress = (address, targetFormat) => {
     throw new Error(`Unsupported address format: ${address}`);
 };
 
+/**
+ * USDC token definition with addresses and metadata.
+ *
+ * @remarks
+ * This is the built-in USDC definition used by the TokenRegistry.
+ * Includes all known USDC addresses across supported chains.
+ *
+ * Keys use the `Blockchain` enum for type safety. Both enum values
+ * and string literals are supported:
+ * - `Blockchain.Ethereum` or `'Ethereum'`
+ *
+ * @example
+ * ```typescript
+ * import { USDC } from '@core/tokens'
+ * import { Blockchain } from '@core/chains'
+ *
+ * console.log(USDC.symbol)   // 'USDC'
+ * console.log(USDC.decimals) // 6
+ * console.log(USDC.locators[Blockchain.Ethereum])
+ * // '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
+ * ```
+ */
+const USDC = {
+    symbol: 'USDC',
+    decimals: 6,
+    locators: {
+        // =========================================================================
+        // Mainnets (alphabetically sorted)
+        // =========================================================================
+        [exports.Blockchain.Arbitrum]: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
+        [exports.Blockchain.Avalanche]: '0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E',
+        [exports.Blockchain.Base]: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        [exports.Blockchain.Celo]: '0xcebA9300f2b948710d2653dD7B07f33A8B32118C',
+        [exports.Blockchain.Codex]: '0xd996633a415985DBd7D6D12f4A4343E31f5037cf',
+        [exports.Blockchain.Ethereum]: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+        [exports.Blockchain.Hedera]: '0.0.456858',
+        [exports.Blockchain.HyperEVM]: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
+        [exports.Blockchain.Ink]: '0x2D270e6886d130D724215A266106e6832161EAEd',
+        [exports.Blockchain.Linea]: '0x176211869ca2b568f2a7d4ee941e073a821ee1ff',
+        [exports.Blockchain.Monad]: '0x754704Bc059F8C67012fEd69BC8A327a5aafb603',
+        [exports.Blockchain.NEAR]: '17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1',
+        [exports.Blockchain.Noble]: 'uusdc',
+        [exports.Blockchain.Optimism]: '0x0b2c639c533813f4aa9d7837caf62653d097ff85',
+        [exports.Blockchain.Plume]: '0x222365EF19F7947e5484218551B56bb3965Aa7aF',
+        [exports.Blockchain.Polkadot_Asset_Hub]: '1337',
+        [exports.Blockchain.Polygon]: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359',
+        [exports.Blockchain.Sei]: '0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392',
+        [exports.Blockchain.Solana]: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+        [exports.Blockchain.Sonic]: '0x29219dd400f2Bf60E5a23d13Be72B486D4038894',
+        [exports.Blockchain.Stellar]: 'USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
+        [exports.Blockchain.Sui]: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
+        [exports.Blockchain.Unichain]: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
+        [exports.Blockchain.World_Chain]: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
+        [exports.Blockchain.XDC]: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
+        [exports.Blockchain.ZKSync_Era]: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
+        // =========================================================================
+        // Testnets (alphabetically sorted)
+        // =========================================================================
+        [exports.Blockchain.Arbitrum_Sepolia]: '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
+        [exports.Blockchain.Avalanche_Fuji]: '0x5425890298aed601595a70AB815c96711a31Bc65',
+        [exports.Blockchain.Base_Sepolia]: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+        [exports.Blockchain.Codex_Testnet]: '0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f',
+        [exports.Blockchain.Ethereum_Sepolia]: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
+        [exports.Blockchain.Hedera_Testnet]: '0.0.429274',
+        [exports.Blockchain.HyperEVM_Testnet]: '0x2B3370eE501B4a559b57D449569354196457D8Ab',
+        [exports.Blockchain.Ink_Testnet]: '0xFabab97dCE620294D2B0b0e46C68964e326300Ac',
+        [exports.Blockchain.Linea_Sepolia]: '0xfece4462d57bd51a6a552365a011b95f0e16d9b7',
+        [exports.Blockchain.Monad_Testnet]: '0x534b2f3A21130d7a60830c2Df862319e593943A3',
+        [exports.Blockchain.NEAR_Testnet]: '3e2210e1184b45b64c8a434c0a7e7b23cc04ea7eb7a6c3c32520d03d4afcb8af',
+        [exports.Blockchain.Noble_Testnet]: 'uusdc',
+        [exports.Blockchain.Optimism_Sepolia]: '0x5fd84259d66Cd46123540766Be93DFE6D43130D7',
+        [exports.Blockchain.Plume_Testnet]: '0xcB5f30e335672893c7eb944B374c196392C19D18',
+        [exports.Blockchain.Polkadot_Westmint]: '31337',
+        [exports.Blockchain.Polygon_Amoy_Testnet]: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
+        [exports.Blockchain.Sei_Testnet]: '0x4fCF1784B31630811181f670Aea7A7bEF803eaED',
+        [exports.Blockchain.Solana_Devnet]: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU',
+        [exports.Blockchain.Sonic_Testnet]: '0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51',
+        [exports.Blockchain.Stellar_Testnet]: 'USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5',
+        [exports.Blockchain.Sui_Testnet]: '0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC',
+        [exports.Blockchain.Unichain_Sepolia]: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
+        [exports.Blockchain.World_Chain_Sepolia]: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
+        [exports.Blockchain.XDC_Apothem]: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
+        [exports.Blockchain.ZKSync_Sepolia]: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853',
+    },
+};
+
+/**
+ * USDT (Tether) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in USDT definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains.
+ */
+const USDT = {
+    symbol: 'USDT',
+    decimals: 6,
+    locators: {
+        [exports.Blockchain.Aptos]: '0x357b0b74bc833e95a115ad22604854d6b0fca151cecd94111770e5d6ffc9dc2b',
+        [exports.Blockchain.Arbitrum]: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9',
+        [exports.Blockchain.Avalanche]: '0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7',
+        [exports.Blockchain.Celo]: '0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e',
+        [exports.Blockchain.Ethereum]: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
+        [exports.Blockchain.HyperEVM]: '0xb8ce59fc3717ada4c02eadf9682a9e934f625ebb',
+        [exports.Blockchain.Ink]: '0x0200C29006150606B650577BBE7B6248F58470c1',
+        [exports.Blockchain.Linea]: '0xA219439258ca9da29E9Cc4cE5596924745e12B93',
+        [exports.Blockchain.Monad]: '0xe7cd86e13AC4309349F30B3435a9d337750fC82D',
+        [exports.Blockchain.NEAR]: 'usdt.tether-token.near',
+        [exports.Blockchain.Optimism]: '0x94b008aA00579c1307B0EF2c499aD98a8ce58e58',
+        [exports.Blockchain.Polkadot_Asset_Hub]: '1984',
+        [exports.Blockchain.Polygon]: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
+        [exports.Blockchain.Sei]: '0x9151434b16b9763660705744891fA906F660EcC5',
+        [exports.Blockchain.Solana]: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
+        [exports.Blockchain.Unichain]: '0x9151434b16b9763660705744891fA906F660EcC5',
+    },
+};
+
+/**
+ * EURC (Euro Coin) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in EURC definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains.
+ */
+const EURC = {
+    symbol: 'EURC',
+    decimals: 6,
+    locators: {
+        [exports.Blockchain.Avalanche]: '0xc891EB4cbdEFf6e073e859e987815Ed1505c2ACD',
+        [exports.Blockchain.Base]: '0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42',
+        [exports.Blockchain.Ethereum]: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
+        [exports.Blockchain.Solana]: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
+        [exports.Blockchain.World_Chain]: '0x1C60ba0A0eD1019e8Eb035E6daF4155A5cE2380B',
+    },
+};
+
+/**
+ * DAI (Maker DAO) stablecoin token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in DAI definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains.
+ */
+const DAI = {
+    symbol: 'DAI',
+    decimals: 18,
+    chainDecimals: {
+        [exports.Blockchain.Solana]: 8,
+    },
+    locators: {
+        [exports.Blockchain.Arbitrum]: '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1',
+        [exports.Blockchain.Avalanche]: '0xd586E7F844cEa2F87f50152665BCbc2C279D8d70',
+        [exports.Blockchain.Base]: '0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb',
+        [exports.Blockchain.Ethereum]: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
+        [exports.Blockchain.Linea]: '0x4AF15ec2A0BD43Db75dd04E62FAA3B8EF36b00d5',
+        [exports.Blockchain.Optimism]: '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1',
+        [exports.Blockchain.Polygon]: '0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063',
+        [exports.Blockchain.Solana]: 'EjmyN6qEC1Tf1JxiG1ae7UTJhUxSwk1TCWNWqxWV4J6o',
+    },
+};
+
+/**
+ * USDe (Ethena) synthetic dollar token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in USDE definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains.
+ */
+const USDE = {
+    symbol: 'USDe',
+    decimals: 18,
+    chainDecimals: {
+        [exports.Blockchain.Solana]: 9,
+    },
+    locators: {
+        [exports.Blockchain.Arbitrum]: '0x5d3a1Ff2b6BAb83b63cd9AD0787074081a52ef34',
+        [exports.Blockchain.Base]: '0x5d3a1Ff2b6BAb83b63cd9AD0787074081a52ef34',
+        [exports.Blockchain.Ethereum]: '0x4c9EDD5852cd905f086C759E8383e09bff1E68B3',
+        [exports.Blockchain.Linea]: '0x5d3a1Ff2b6BAb83b63cd9AD0787074081a52ef34',
+        [exports.Blockchain.Optimism]: '0x5d3a1Ff2b6BAb83b63cd9AD0787074081a52ef34',
+        [exports.Blockchain.Solana]: 'DEkqHyPN7GMRJ5cArtQFAWefqbZb33Hyf6s5iCwjEonT',
+    },
+};
+
+/**
+ * PYUSD (PayPal USD) stablecoin token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in PYUSD definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains.
+ */
+const PYUSD = {
+    symbol: 'PYUSD',
+    decimals: 6,
+    locators: {
+        [exports.Blockchain.Arbitrum]: '0x46850aD61C2B7d64d08c9C754F45254596696984',
+        [exports.Blockchain.Ethereum]: '0x6c3ea9036406852006290770BEdFcAbA0e23A0e8',
+        [exports.Blockchain.Solana]: '2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo',
+    },
+};
+
+/**
+ * WETH (Wrapped Ether) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in WETH definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains where WETH is available.
+ */
+const WETH = {
+    symbol: 'WETH',
+    decimals: 18,
+    chainDecimals: {
+        [exports.Blockchain.Solana]: 9,
+    },
+    locators: {
+        [exports.Blockchain.Arbitrum]: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1',
+        [exports.Blockchain.Avalanche]: '0x49D5c2BdFfac6CE2BFdB6640F4F80f226bc10bAB',
+        [exports.Blockchain.Base]: '0x4200000000000000000000000000000000000006',
+        [exports.Blockchain.Ethereum]: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
+        [exports.Blockchain.Optimism]: '0x4200000000000000000000000000000000000006',
+        [exports.Blockchain.Polygon]: '0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619',
+        [exports.Blockchain.Solana]: '7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs',
+    },
+};
+
+/**
+ * WBTC (Wrapped Bitcoin) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in WBTC definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains where WBTC is available.
+ */
+const WBTC = {
+    symbol: 'WBTC',
+    decimals: 8,
+    locators: {
+        [exports.Blockchain.Ethereum]: '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599',
+        [exports.Blockchain.Arbitrum]: '0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f',
+        [exports.Blockchain.Avalanche]: '0x50b7545627a5162F82A992c33b87aDc75187B218',
+    },
+};
+
+/**
+ * WSOL (Wrapped SOL) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in WSOL definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains where WSOL is available.
+ */
+const WSOL = {
+    symbol: 'WSOL',
+    decimals: 9,
+    locators: {
+        [exports.Blockchain.Solana]: 'So11111111111111111111111111111111111111112',
+    },
+};
+
+/**
+ * WAVAX (Wrapped AVAX) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in WAVAX definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains where WAVAX is available.
+ */
+const WAVAX = {
+    symbol: 'WAVAX',
+    decimals: 18,
+    locators: {
+        [exports.Blockchain.Avalanche]: '0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7',
+    },
+};
+
+/**
+ * WPOL (Wrapped POL) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in WPOL definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains where WPOL is available.
+ */
+const WPOL = {
+    symbol: 'WPOL',
+    decimals: 18,
+    locators: {
+        [exports.Blockchain.Polygon]: '0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270',
+    },
+};
+
+/**
+ * ETH (native Ether alias) token definition with metadata.
+ *
+ * @remarks
+ * Built-in ETH definition for the TokenRegistry. Used as a symbol alias
+ * for native ETH (e.g. in swap flows). Chain locators are TBD and will
+ * be added when addresses are available. Use raw selector with
+ * locator + decimals where native gas token is represented as a contract.
+ */
+const ETH = {
+    symbol: 'ETH',
+    decimals: 18,
+    locators: {},
+};
+
+/**
+ * POL (Polygon native token) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in POL definition for the TokenRegistry. Includes chain locators
+ * where POL is available as a bridged/wrapped asset.
+ */
+const POL = {
+    symbol: 'POL',
+    decimals: 18,
+    locators: {
+        [exports.Blockchain.Ethereum]: '0x455e53CBB86018Ac2B8092FdCd39d8444aFFC3F6',
+    },
+};
+
+/**
+ * PLUME (Plume network token) token definition with addresses and metadata.
+ *
+ * @remarks
+ * Built-in PLUME definition for the TokenRegistry. Includes chain locators
+ * where PLUME is available.
+ */
+const PLUME = {
+    symbol: 'PLUME',
+    decimals: 18,
+    locators: {
+        [exports.Blockchain.Ethereum]: '0x4C1746A800D224393fE2470C70A35717eD4eA5F1',
+    },
+};
+
+/**
+ * MON token definition with Solana mint metadata.
+ *
+ * @remarks
+ * Built-in MON definition for the TokenRegistry. Includes chain locators
+ * for swap-supported chains.
+ */
+const MON = {
+    symbol: 'MON',
+    decimals: 18,
+    chainDecimals: {
+        [exports.Blockchain.Solana]: 8,
+    },
+    locators: {
+        [exports.Blockchain.Solana]: 'CrAr4RRJMBVwRsZtT62pEhfA9H5utymC2mVx8e7FreP2',
+    },
+};
+
+// Re-export for consumers
+/**
+ * All default token definitions.
+ *
+ * @remarks
+ * These tokens are automatically included in the TokenRegistry when created
+ * without explicit defaults. Extensions can override these definitions.
+ * Includes USDC, USDT, EURC, DAI, USDE, PYUSD, WETH, WBTC, WSOL, WAVAX,
+ * WPOL, ETH, POL, PLUME, and MON.
+ *
+ * @example
+ * ```typescript
+ * import { createTokenRegistry } from '@core/tokens'
+ *
+ * // Registry uses these by default
+ * const registry = createTokenRegistry()
+ *
+ * // Add custom tokens (built-ins are still included)
+ * const customRegistry = createTokenRegistry({
+ *   tokens: [myCustomToken],
+ * })
+ * ```
+ */
+const DEFAULT_TOKENS = [
+    USDC,
+    USDT,
+    EURC,
+    DAI,
+    USDE,
+    PYUSD,
+    WETH,
+    WBTC,
+    WSOL,
+    WAVAX,
+    WPOL,
+    ETH,
+    POL,
+    PLUME,
+    MON,
+];
+/**
+ * Uppercased token symbols approved for swap fee collection.
+ *
+ * @remarks
+ * Derived from {@link DEFAULT_TOKENS} so all consumers share a single
+ * allowlist source and stay in sync when defaults change.
+ */
+new Set(DEFAULT_TOKENS.map((t) => t.symbol.toUpperCase()));
+
+/**
+ * Define a schema for token registry interfaces.
+ *
+ * @remarks
+ * Validate that a registry exposes the `resolve()` API used by adapters.
+ *
+ * @example
+ * ```typescript
+ * import { tokenRegistrySchema } from '@core/tokens'
+ *
+ * const registry = {
+ *   resolve: () => ({ locator: '0x0', decimals: 6 }),
+ * }
+ *
+ * tokenRegistrySchema.parse(registry)
+ * ```
+ */
+zod.z.custom((value) => {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    return (typeof record['resolve'] === 'function' &&
+        typeof record['get'] === 'function' &&
+        typeof record['has'] === 'function' &&
+        typeof record['symbols'] === 'function' &&
+        typeof record['entries'] === 'function');
+}, {
+    message: 'Invalid token registry',
+});
+
 /**
  * Schema for validating hexadecimal strings with '0x' prefix.
  *
@@ -5108,9 +6324,27 @@ const adapterSchema = zod.z.object({
  * console.log('EVM address is valid')
  * ```
  */
-function assertEvmAddress(address) {
-    validateOrThrow(address, evmAddressSchema, 'Invalid EVM address');
-}
+function assertEvmAddress(address) {
+    validateOrThrow(address, evmAddressSchema, 'Invalid EVM address');
+}
+
+/**
+ * Permit signature standards for gasless token approvals.
+ *
+ * Defines the permit types that can be used to approve token spending
+ * without requiring a separate approval transaction.
+ *
+ * @remarks
+ * - NONE: No permit, tokens must be pre-approved via separate transaction
+ * - EIP2612: Standard ERC-20 permit (USDC, DAI v2, and most modern tokens)
+ */
+var PermitType;
+(function (PermitType) {
+    /** No permit required - tokens must be pre-approved */
+    PermitType[PermitType["NONE"] = 0] = "NONE";
+    /** EIP-2612 standard permit */
+    PermitType[PermitType["EIP2612"] = 1] = "EIP2612";
+})(PermitType || (PermitType = {}));
 
 /**
  * Creates a no-op prepared chain request.
@@ -5219,6 +6453,12 @@ function getSupportedChains(ecosystem) {
  *
  * This ABI is used to interact with generic ERC20 tokens on EVM networks.
  *
+ * @remarks
+ * The `approve`, `transfer` and `transferFrom` functions have been modified to not expect a return value
+ * (empty `outputs` array) to support non-standard implementations like USDT
+ * that return `void` instead of `bool`. This is safe because the SDK never
+ * uses the return value from these functions - only the transaction hash matters.
+ *
  * @see https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md
  */
 const erc20Abi = [
@@ -5249,12 +6489,7 @@ const erc20Abi = [
             },
         ],
         name: 'approve',
-        outputs: [
-            {
-                name: '',
-                type: 'bool',
-            },
-        ],
+        outputs: [],
         payable: false,
         stateMutability: 'nonpayable',
         type: 'function',
@@ -5290,12 +6525,7 @@ const erc20Abi = [
             },
         ],
         name: 'transferFrom',
-        outputs: [
-            {
-                name: '',
-                type: 'bool',
-            },
-        ],
+        outputs: [],
         payable: false,
         stateMutability: 'nonpayable',
         type: 'function',
@@ -5360,12 +6590,7 @@ const erc20Abi = [
             },
         ],
         name: 'transfer',
-        outputs: [
-            {
-                name: '',
-                type: 'bool',
-            },
-        ],
+        outputs: [],
         payable: false,
         stateMutability: 'nonpayable',
         type: 'function',
@@ -8588,6 +9813,78 @@ 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',
+    },
+];
+
 /**
  * Core type definitions for EVM-compatible blockchain transaction execution
  * and gas estimation.
@@ -8597,6 +9894,66 @@ const bridgeContractAbi = [
  *
  * @module constants
  */
+/**
+ * The zero address constant for EVM chains.
+ *
+ * @remarks
+ * This 20-byte address (`0x00...00`) is commonly used to represent:
+ * - Disabled token approvals in instructions (tokenIn = ZERO_ADDRESS)
+ * - Disabled balance validations (tokenOut = ZERO_ADDRESS)
+ * - Null/unset address values
+ *
+ * **Note**: For native currency representation in adapter contract instructions,
+ * use {@link NATIVE_TOKEN_ADDRESS} (`0xEeee...`) instead.
+ *
+ * @example
+ * ```typescript
+ * import { ZERO_ADDRESS } from '@core/adapter-evm'
+ *
+ * // Check if instruction has no token output (validation disabled)
+ * if (instruction.tokenOut === ZERO_ADDRESS) {
+ *   // No output validation needed
+ * }
+ * ```
+ */
+/**
+ * The native token address constant used by the Adapter Contract.
+ *
+ * @remarks
+ * This address (`0xEeee...`) is the standard convention used by DEX aggregators
+ * and the Adapter Contract to represent native currency (ETH, MATIC, AVAX, etc.)
+ * in swap instructions.
+ *
+ * **Address Conventions in Adapter Contract:**
+ * - Native Token: `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`
+ * - No Token: `0x0000000000000000000000000000000000000000` (ZERO_ADDRESS)
+ * - ERC20: Any other valid address
+ *
+ * **Native currency swaps:**
+ * - When `tokenIn === NATIVE_TOKEN_ADDRESS`, value is sent via tx.value
+ * - No approval or permit is required for native currency
+ * - Used in instructions from stablecoin-service for ETH/MATIC/AVAX swaps
+ *
+ * @example
+ * ```typescript
+ * import { NATIVE_TOKEN_ADDRESS, ZERO_ADDRESS } from '@core/adapter-evm'
+ *
+ * // Check if token requires approval (exclude native and zero)
+ * function requiresApproval(tokenAddress: string): boolean {
+ *   const normalized = tokenAddress.toLowerCase()
+ *   return normalized !== NATIVE_TOKEN_ADDRESS.toLowerCase() &&
+ *          normalized !== ZERO_ADDRESS.toLowerCase()
+ * }
+ *
+ * // Example: ETH → USDC swap
+ * const instruction = {
+ *   tokenIn: NATIVE_TOKEN_ADDRESS, // No approval needed
+ *   amount: 1000000000000000000n, // 1 ETH
+ *   value: 1000000000000000000n, // Sent via tx.value
+ * }
+ * ```
+ */
+const NATIVE_TOKEN_ADDRESS = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE';
 /**
  * A constant representing the zero hash value.
  *
@@ -9217,6 +10574,58 @@ const customBurnWithHook = async (params, adapter, context) => {
     return prepareCustomBurn(params, adapter, context);
 };
 
+/**
+ * Prepare an EVM-compatible native token transfer transaction.
+ *
+ * Create a prepared chain request to move native tokens from the caller's wallet to a
+ * recipient address on EVM chains.
+ *
+ * The function validates that the current chain is EVM-compatible, then builds a
+ * transaction targeting the provided recipient address. The resulting prepared
+ * request can be simulated or executed by the caller.
+ *
+ * @param params - The action payload for `native.transfer` containing:
+ *   - `to`: The recipient wallet address.
+ *   - `amount`: The native token amount (as a `bigint`).
+ *   - `chain`: The chain to transfer the native tokens on.
+ * @param adapter - The EVM adapter responsible for chain context and transaction preparation.
+ * @returns A promise that resolves to a prepared chain request for the `transfer` call.
+ * @throws {KitError} If chain is not EVM (INPUT_INVALID_CHAIN) or amount is invalid (INPUT_INVALID_AMOUNT).
+ *
+ * @example
+ * ```typescript
+ * const prepared = await transfer(
+ *   {
+ *     to: '0x1111111111111111111111111111111111111111',
+ *     amount: 1_000_000n,
+ *     chain: 'Ethereum_Sepolia',
+ *   },
+ *   adapter
+ * );
+ * await prepared.execute();
+ * ```
+ */
+const transfer$3 = async (params, adapter, context) => {
+    const chain = context.chain;
+    if (chain.type !== 'evm') {
+        throw createInvalidChainError(chain.name, `Expected EVM chain definition, but received chain type: ${chain.type}`);
+    }
+    const { to, amount } = params;
+    // Validate the amount
+    if (typeof amount !== 'bigint' || amount <= 0n) {
+        throw createInvalidAmountError(String(amount), 'Transfer amount must be a positive bigint');
+    }
+    // Validate the to address
+    assertEvmAddress(to);
+    // Prepare the transfer transaction
+    // Note: Type assertion needed - native transfers don't use contract ABI
+    return adapter.prepare({
+        type: 'evm',
+        address: to,
+        value: amount,
+    }, context);
+};
+
 /**
  * Prepares an EVM-compatible native token balance read (ETH, MATIC, etc.).
  *
@@ -9271,6 +10680,159 @@ const balanceOf$2 = async (params, adapter, context) => {
     };
 };
 
+/**
+ * Type guard to check if params is ExecuteSwapEVMParams.
+ *
+ * Uses property-based narrowing: EVM swap params have `executeParams`, `tokenInputs`,
+ * `inputAmount`, and `tokenInAddress`, while Solana swap params have `serializedTransaction`.
+ *
+ * @remarks
+ * Checks both property existence and that values are not undefined to provide
+ * robust runtime validation against malformed inputs.
+ */
+const isEVMSwapParams = (params) => {
+    return ('executeParams' in params &&
+        params.executeParams !== undefined &&
+        'tokenInputs' in params &&
+        params.tokenInputs !== undefined &&
+        'inputAmount' in params &&
+        params.inputAmount !== undefined &&
+        'tokenInAddress' in params &&
+        params.tokenInAddress !== undefined);
+};
+/**
+ * Executes a swap transaction via the Adapter smart contract.
+ *
+ * This action prepares swap transactions that execute through the Adapter
+ * Contract, which handles gasless token approvals via permits (EIP-2612,
+ * Permit2, etc.) and executes multi-step swap instructions atomically.
+ *
+ * @remarks
+ * **Adapter Contract Pattern**
+ *
+ * The Adapter Contract pattern enables single-transaction swaps with gasless
+ * approvals. The flow is:
+ * 1. Service provides `executeParams` (swap instructions) and `signature` (proxy authorization)
+ * 2. SDK builds `tokenInputs` with permit signatures for token approvals
+ * 3. SDK calls AdapterContract.execute(executeParams, tokenInputs, signature)
+ * 4. Adapter pulls tokens via permits, executes swaps, validates outputs, sweeps residuals
+ *
+ * **Permit Support**
+ *
+ * Token approvals are handled via permits encoded in `tokenInputs`. The SDK
+ * constructs `TokenInput` objects with `permitCalldata` containing the encoded
+ * permit signature. The Adapter Contract executes these permits on-chain before
+ * executing swap instructions, enabling gasless approvals in a single atomic transaction.
+ *
+ * Supported permit types: EIP-2612, Permit2, DAI-like, EIP-3009
+ *
+ * **Service Integration**
+ *
+ * The `executeParams` and `signature` come from the stablecoin-service `createSwap`
+ * endpoint. These are EIP-712 signed by Circle's proxy service and must be passed
+ * to the Adapter Contract exactly as received (no modification).
+ *
+ * @param params - Swap execution parameters:
+ *   - `executeParams`: Execution parameters from service (instructions, tokens, execId, deadline)
+ *   - `tokenInputs`: Token inputs with permit signatures (built by provider)
+ *   - `signature`: EIP-712 signature from service (proxy authorization)
+ *   - `inputAmount`: User's swap input amount from service response (source of truth)
+ * @param adapter - EVM adapter for transaction preparation
+ * @param context - Resolved operation context with chain and address information
+ * @returns Prepared chain request ready for estimation or execution
+ *
+ * @throws KitError If chain is not EVM-compatible (INPUT_INVALID_CHAIN)
+ * @throws KitError If executeParams is missing or invalid (INPUT_VALIDATION_FAILED)
+ * @throws KitError If signature is invalid (INPUT_VALIDATION_FAILED)
+ * @throws KitError If tokenInputs is not an array (INPUT_VALIDATION_FAILED)
+ *
+ * @example
+ * ```typescript
+ * import { createSwap } from '@core/service-client'
+ * import { PermitType } from '@core/adapter'
+ * import type { EvmAdapter } from '@core/adapter-evm'
+ *
+ * // 1. Get swap transaction from stablecoin-service
+ * const swapResponse = await createSwap({
+ *   tokenInAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
+ *   tokenOutAddress: '0xdAC17F958D2ee523a2206206994597C13D831ec8', // USDT
+ *   tokenInChain: 'Ethereum',
+ *   fromAddress: await adapter.getAddress(),
+ *   toAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
+ *   amount: '1000000', // 1 USDC in base units
+ *   apiKey: process.env.API_KEY,
+ * })
+ *
+ * // 2. Build token inputs with permit signature (provider responsibility)
+ * const tokenInputs: TokenInput[] = [{
+ *   permitType: PermitType.EIP2612,
+ *   token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *   from: await adapter.getAddress(Ethereum),
+ *   amount: 1000000n,
+ *   permitCalldata: '0x...' // Encoded permit signature from provider
+ * }]
+ *
+ * // 3. Execute swap via adapter action
+ * const swapRequest = await adapter.prepareAction(
+ *   'swap.execute',
+ *   {
+ *     executeParams: swapResponse.transaction.executeParams,
+ *     tokenInputs,
+ *     signature: swapResponse.transaction.signature,
+ *     inputAmount: BigInt(swapResponse.amount) // From service response
+ *   },
+ *   context
+ * )
+ *
+ * // 4. Estimate gas
+ * const gasEstimate = await swapRequest.estimate()
+ * console.log('Gas required:', gasEstimate.gas)
+ *
+ * // 5. Execute transaction
+ * const txHash = await swapRequest.execute()
+ * console.log('Swap transaction:', txHash)
+ * ```
+ */
+const executeSwap = async (params, adapter, context) => {
+    const { chain } = context;
+    // Validate EVM chain first (this is an EVM-specific action)
+    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 createInvalidChainError(chain.name, `Swap action is not supported on this chain: ${chain.name}`);
+    }
+    // Narrow type using property-based guard - this function only handles EVM swaps
+    if (!isEVMSwapParams(params)) {
+        throw createValidationFailedError('params', 'Invalid or incomplete EVM swap parameters', 'This action handler only supports EVM swap parameters (must have executeParams and tokenInputs)');
+    }
+    // Validate executeParams exists
+    if (typeof params.executeParams !== 'object') {
+        throw createValidationFailedError('executeParams', params.executeParams, 'ExecuteParams is required from service response');
+    }
+    // Validate signature
+    if (params.signature === '0x') {
+        throw createValidationFailedError('signature', params.signature, 'Signature is required from service response');
+    }
+    // Validate tokenInputs array (can be empty if no permits needed)
+    if (!Array.isArray(params.tokenInputs)) {
+        throw createValidationFailedError('tokenInputs', params.tokenInputs, 'TokenInputs must be an array');
+    }
+    // Check if swapping native currency (ETH, MATIC, etc.) vs ERC20 tokens
+    const isNativeSwap = params.tokenInAddress.toLowerCase() === NATIVE_TOKEN_ADDRESS.toLowerCase();
+    // Prepare transaction to Adapter Contract
+    return adapter.prepare({
+        type: 'evm',
+        abi: adapterContractAbi,
+        address: adapterContractAddress,
+        functionName: 'execute',
+        args: [params.executeParams, params.tokenInputs, params.signature],
+        // Include value only for native currency swaps (ETH → USDC, etc.)
+        ...(isNativeSwap && { value: params.inputAmount }),
+    }, context);
+};
+
 /**
  * Prepares an EVM-compatible `balanceOf` read for any ERC-20 token.
  *
@@ -9319,66 +10881,228 @@ const balanceOf$1 = async (params, adapter, context) => {
             args: [walletAddress],
         }, context);
     }
-    catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to get token balance for ${walletAddress} from ${tokenAddress}: ${errorMessage}`);
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to get token balance for ${walletAddress} from ${tokenAddress}: ${errorMessage}`);
+    }
+};
+
+/**
+ * Prepares an EVM-compatible `allowance` read for any ERC-20 token.
+ *
+ * This function creates a prepared chain request for reading the allowance of a given wallet (owner)
+ * and delegate (spender) address for a specified ERC-20 token on an EVM-based chain. It validates the chain type
+ * and all addresses, then constructs a read-only contract call using the canonical ERC-20 ABI and the provided token address.
+ * The resulting prepared request can be executed or simulated by the caller.
+ *
+ * @param params - The action payload containing:
+ *   - `tokenAddress`: The contract address of the ERC-20 token.
+ *   - `walletAddress`: The address of the token owner (if not provided, will use the adapter's address).
+ *   - `delegate`: The address to check the allowance for (spender).
+ * @param adapter - The EVM adapter responsible for chain context and contract interaction.
+ * @param context - The resolved operation context providing chain and address information.
+ * @returns A promise that resolves to a prepared chain request for the `allowance` call.
+ *   The `execute` method returns the allowance as a string (in the token's smallest unit).
+ * @throws Error if the current chain is not EVM-compatible, if address validation fails, or if the contract call fails.
+ *
+ * @example
+ * ```typescript
+ * const prepared = await allowance(
+ *   { tokenAddress: '0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', walletAddress: '0xabc...', delegate: '0xdef...' },
+ *   adapter,
+ *   context
+ * );
+ * const allowance = await prepared.execute();
+ * console.log(allowance); // e.g., "1000000" (for 1 USDC allowance with 6 decimals)
+ * ```
+ */
+const allowance$1 = async (params, adapter, context) => {
+    const chain = context.chain;
+    if (chain.type !== 'evm') {
+        throw new Error(`Expected EVM chain definition, but received chain type: ${chain.type}`);
+    }
+    const { tokenAddress, walletAddress: walletAddressParam, delegate } = params;
+    // Use provided wallet address or fall back to context address
+    const walletAddress = walletAddressParam ?? context.address;
+    // validate the address
+    assertEvmAddress(walletAddress);
+    assertEvmAddress(tokenAddress);
+    assertEvmAddress(delegate);
+    try {
+        return await adapter.prepare({
+            type: 'evm',
+            address: tokenAddress,
+            abi: erc20Abi,
+            functionName: 'allowance',
+            args: [walletAddress, delegate],
+        }, context);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to get token allowance for ${walletAddress} from ${tokenAddress}: ${errorMessage}`);
+    }
+};
+
+/**
+ * Prepares an EVM-compatible `approve` transaction for any ERC-20 token.
+ *
+ * This function creates a prepared chain request for approving a delegate (spender)
+ * to spend a specified amount of tokens on behalf of the caller. It validates the
+ * chain type and all addresses, then constructs a transaction using the standard
+ * ERC-20 ABI and the provided token address. The resulting prepared request can be
+ * executed or simulated by the caller.
+ *
+ * @remarks
+ * **Race Condition Consideration**
+ *
+ * The standard ERC-20 `approve()` function has a known theoretical race condition
+ * where a malicious spender could front-run an approval change to spend both the
+ * old and new allowance amounts. However, this is rare in practice and is the
+ * accepted industry standard used by major protocols (Uniswap, 1inch, etc.).
+ *
+ * @param params - The action payload containing:
+ *   - `tokenAddress`: The contract address of the ERC-20 token.
+ *   - `delegate`: The address to grant the allowance to (spender).
+ *   - `amount`: The amount of tokens to approve (as a bigint, in the token's smallest unit).
+ * @param adapter - The EVM adapter responsible for chain context and transaction preparation.
+ * @param context - The resolved operation context providing chain and address information.
+ * @returns A promise that resolves to a prepared chain request for the `approve` call.
+ *   The `execute` method returns the transaction hash.
+ * @throws {KitError} If the current chain is not EVM-compatible (INPUT_INVALID_CHAIN).
+ * @throws {KitError} if the amount is not a postive or zero bigint (INPUT_INVALID_AMOUNT).
+ * @throws {ValidationError} If address validation fails for tokenAddress or delegate.
+ *
+ * @example Approve USDT for a swap contract
+ * ```typescript
+ * import { approve } from '@core/adapter-evm/actions/token'
+ * import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+ * import { Ethereum } from '@core/chains'
+ *
+ * const adapter = createAdapterFromPrivateKey({ privateKey: '0x...' })
+ * const context = {
+ *   chain: Ethereum,
+ *   address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
+ * }
+ *
+ * // Approve 100 USDT (6 decimals) for a swap contract
+ * const prepared = await approve(
+ *   {
+ *     tokenAddress: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDT
+ *     delegate: '0x1234567890123456789012345678901234567890', // Swap contract
+ *     amount: 100_000000n // 100 USDT
+ *   },
+ *   adapter,
+ *   context
+ * )
+ *
+ * // Execute the approval
+ * const txHash = await prepared.execute()
+ * console.log('Approval transaction:', txHash)
+ * ```
+ *
+ * @example Approve DAI for a lending protocol
+ * ```typescript
+ * // Approve 1000 DAI (18 decimals) for a lending protocol
+ * const prepared = await approve(
+ *   {
+ *     tokenAddress: '0x6B175474E89094C44Da98b954EedeAC495271d0F', // DAI
+ *     delegate: '0xLendingProtocolAddress',
+ *     amount: 1000_000000000000000000n // 1000 DAI
+ *   },
+ *   adapter,
+ *   context
+ * )
+ *
+ * await prepared.execute()
+ * ```
+ *
+ * @example Revoke approval by setting to zero
+ * ```typescript
+ * // Revoke approval by setting allowance to 0
+ * const prepared = await approve(
+ *   {
+ *     tokenAddress: '0xTokenAddress',
+ *     delegate: '0xSpenderAddress',
+ *     amount: 0n // Revoke approval
+ *   },
+ *   adapter,
+ *   context
+ * )
+ *
+ * await prepared.execute()
+ * ```
+ */
+const approve = async (params, adapter, context) => {
+    const chain = context.chain;
+    if (chain.type !== 'evm') {
+        throw createInvalidChainError(chain.name, `Expected EVM chain definition, but received chain type: ${chain.type}`);
+    }
+    const { tokenAddress, delegate, amount } = params;
+    // Validate addresses
+    assertEvmAddress(tokenAddress);
+    assertEvmAddress(delegate);
+    // Validate amount (must be bigint and >= 0)
+    if (typeof amount !== 'bigint' || amount < 0n) {
+        throw createInvalidAmountError(String(amount), 'Approval amount must be a non-negative bigint');
     }
+    // Prepare the approve transaction
+    return adapter.prepare({
+        type: 'evm',
+        abi: erc20Abi,
+        address: tokenAddress,
+        functionName: 'approve',
+        args: [delegate, amount],
+    }, context);
 };
 
 /**
- * Prepares an EVM-compatible `allowance` read for any ERC-20 token.
+ * Prepare an EVM-compatible ERC-20 `transfer` transaction.
  *
- * This function creates a prepared chain request for reading the allowance of a given wallet (owner)
- * and delegate (spender) address for a specified ERC-20 token on an EVM-based chain. It validates the chain type
- * and all addresses, then constructs a read-only contract call using the canonical ERC-20 ABI and the provided token address.
- * The resulting prepared request can be executed or simulated by the caller.
+ * Create a prepared chain request to move tokens from the caller's wallet to a
+ * recipient address on EVM chains using the standard ERC-20 ABI.
  *
- * @param params - The action payload containing:
- *   - `tokenAddress`: The contract address of the ERC-20 token.
- *   - `walletAddress`: The address of the token owner (if not provided, will use the adapter's address).
- *   - `delegate`: The address to check the allowance for (spender).
- * @param adapter - The EVM adapter responsible for chain context and contract interaction.
- * @param context - The resolved operation context providing chain and address information.
- * @returns A promise that resolves to a prepared chain request for the `allowance` call.
- *   The `execute` method returns the allowance as a string (in the token's smallest unit).
- * @throws Error if the current chain is not EVM-compatible, if address validation fails, or if the contract call fails.
+ * The function validates that the current chain is EVM-compatible, then builds a
+ * transaction targeting the provided token contract address. The resulting prepared
+ * request can be simulated or executed by the caller.
+ *
+ * @param params - The action payload for `token.transfer` containing:
+ *   - `tokenAddress`: The ERC-20 token contract address.
+ *   - `to`: The recipient wallet address.
+ *   - `amount`: The token amount in the smallest unit (as a `bigint`).
+ * @param adapter - The EVM adapter responsible for chain context and transaction preparation.
+ * @returns A promise that resolves to a prepared chain request for the `transfer` call.
+ * @throws {KitError} If chain is not EVM (INPUT_INVALID_CHAIN) or amount is invalid (INPUT_INVALID_AMOUNT).
  *
  * @example
  * ```typescript
- * const prepared = await allowance(
- *   { tokenAddress: '0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', walletAddress: '0xabc...', delegate: '0xdef...' },
- *   adapter,
- *   context
+ * const prepared = await transfer(
+ *   {
+ *     tokenAddress: '0x0000000000000000000000000000000000000000',
+ *     to: '0x1111111111111111111111111111111111111111',
+ *     amount: 1_000_000n,
+ *   },
+ *   adapter
  * );
- * const allowance = await prepared.execute();
- * console.log(allowance); // e.g., "1000000" (for 1 USDC allowance with 6 decimals)
+ * await prepared.execute();
  * ```
  */
-const allowance$1 = async (params, adapter, context) => {
+const transfer$2 = async (params, adapter, context) => {
     const chain = context.chain;
     if (chain.type !== 'evm') {
-        throw new Error(`Expected EVM chain definition, but received chain type: ${chain.type}`);
-    }
-    const { tokenAddress, walletAddress: walletAddressParam, delegate } = params;
-    // Use provided wallet address or fall back to context address
-    const walletAddress = walletAddressParam ?? context.address;
-    // validate the address
-    assertEvmAddress(walletAddress);
-    assertEvmAddress(tokenAddress);
-    assertEvmAddress(delegate);
-    try {
-        return await adapter.prepare({
-            type: 'evm',
-            address: tokenAddress,
-            abi: erc20Abi,
-            functionName: 'allowance',
-            args: [walletAddress, delegate],
-        }, context);
+        throw createInvalidChainError(chain.name, `Expected EVM chain definition, but received chain type: ${chain.type}`);
     }
-    catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to get token allowance for ${walletAddress} from ${tokenAddress}: ${errorMessage}`);
+    // Validate the amount
+    if (typeof params.amount !== 'bigint' || params.amount <= 0n) {
+        throw createInvalidAmountError(String(params.amount), 'Transfer amount must be a positive bigint');
     }
+    // Prepare the transfer transaction
+    return adapter.prepare({
+        type: 'evm',
+        abi: erc20Abi,
+        address: params.tokenAddress,
+        functionName: 'transfer',
+        args: [params.to, params.amount],
+    }, context);
 };
 
 /**
@@ -9508,6 +11232,106 @@ const allowance = async (params, adapter, context) => {
     }, adapter, context);
 };
 
+/**
+ * Prepares a USDC `transfer` transaction for EVM-compatible chains.
+ *
+ * This function validates that the current chain is EVM-compatible and that a canonical
+ * USDC contract address is available for the chain. It then constructs a prepared chain
+ * request to transfer USDC from the caller's wallet to a specified recipient address,
+ * using the standard ERC-20 ABI and the chain's USDC contract address.
+ *
+ * The resulting prepared request can be simulated, estimated, or executed by the caller.
+ *
+ * @param params - The action payload for `usdc.transfer`:
+ *   - `to`: The recipient wallet address.
+ *   - `amount`: The USDC amount to transfer (in the smallest unit, as a `bigint`).
+ * @param adapter - The EVM adapter providing chain context and contract interaction.
+ * @returns A promise resolving to a prepared chain request for the USDC `transfer` call.
+ *   The returned request's `execute` method sends the transaction.
+ * @throws {KitError} If chain is not EVM (INPUT_INVALID_CHAIN) or USDC is not supported (INPUT_UNSUPPORTED_TOKEN).
+ *
+ * @example
+ * ```typescript
+ * const prepared = await transfer(
+ *   {
+ *     to: '0x1111111111111111111111111111111111111111',
+ *     amount: 1_000_000n,
+ *   },
+ *   adapter
+ * );
+ * await prepared.execute();
+ * ```
+ */
+const transfer$1 = async (params, adapter, context) => {
+    const chain = context.chain;
+    if (chain.type !== 'evm') {
+        throw createInvalidChainError(chain.name, `Expected EVM chain definition, but received chain type: ${chain.type}`);
+    }
+    const tokenAddress = chain.usdcAddress;
+    // Check if USDC address exists before validating
+    if (tokenAddress == null) {
+        throw createUnsupportedTokenError('USDC', chain.name);
+    }
+    assertEvmAddress(tokenAddress);
+    // Prepare the usdc transfer transaction using the base token transfer function
+    return transfer$2({
+        tokenAddress,
+        to: params.to,
+        amount: params.amount,
+    }, adapter, context);
+};
+
+/**
+ * Prepares a USDT `transfer` transaction for EVM-compatible chains.
+ *
+ * This function validates that the current chain is EVM-compatible and that a canonical
+ * USDT contract address is available for the chain. It then constructs a prepared chain
+ * request to transfer USDT from the caller's wallet to a specified recipient address,
+ * using the standard ERC-20 ABI and the chain's USDT contract address.
+ *
+ * The resulting prepared request can be simulated, estimated, or executed by the caller.
+ *
+ * @param params - The action payload for `usdt.transfer`:
+ *   - `to`: The recipient wallet address.
+ *   - `amount`: The USDT amount to transfer (in the smallest unit, as a `bigint`).
+ * @param adapter - The EVM adapter providing chain context and contract interaction.
+ * @param context - The resolved operation context containing chain definition.
+ * @returns A promise resolving to a prepared chain request for the USDT `transfer` call.
+ *   The returned request's `execute` method sends the transaction.
+ * @throws {KitError} If chain is not EVM (INPUT_INVALID_CHAIN) or USDT is not supported (INPUT_UNSUPPORTED_TOKEN).
+ *
+ * @example
+ * ```typescript
+ * const prepared = await transfer(
+ *   {
+ *     to: '0x1111111111111111111111111111111111111111',
+ *     amount: 1_000_000n,
+ *   },
+ *   adapter,
+ *   context
+ * );
+ * await prepared.execute();
+ * ```
+ */
+const transfer = async (params, adapter, context) => {
+    const chain = context.chain;
+    if (chain.type !== 'evm') {
+        throw createInvalidChainError(chain.name, `Expected EVM chain, but received chain type: ${chain.type}`);
+    }
+    const tokenAddress = chain.usdtAddress;
+    // Check if USDT address exists before validating
+    if (tokenAddress == null) {
+        throw createUnsupportedTokenError('USDT', chain.name);
+    }
+    assertEvmAddress(tokenAddress);
+    // Prepare the usdt transfer transaction using the base token transfer function
+    return transfer$2({
+        tokenAddress,
+        to: params.to,
+        amount: params.amount,
+    }, adapter, context);
+};
+
 /**
  * Creates a collection of action handlers for EVM blockchain operations.
  *
@@ -9544,6 +11368,15 @@ const getHandlers = (adapter) => {
         'token.balanceOf': async (params, context) => {
             return balanceOf$1(params, adapter, context);
         },
+        /**
+         * Handler for token approve operations on EVM chains.
+         *
+         * Approves a delegate to spend tokens on behalf of the caller.
+         * Uses the standard ERC-20 approve function.
+         */
+        'token.approve': async (params, context) => {
+            return approve(params, adapter, context);
+        },
         /**
          * Handler for USDC allowance operations on EVM chains.
          *
@@ -9607,6 +11440,49 @@ const getHandlers = (adapter) => {
         'cctp.v2.customBurn': async (params, context) => {
             return customBurn(params, adapter, context);
         },
+        /**
+         * Handler for token transfer operations on EVM chains.
+         *
+         * Transfers the specified amount of the token from the caller's wallet to the specified recipient address.
+         */
+        'token.transfer': async (params, context) => {
+            return transfer$2(params, adapter, context);
+        },
+        /**
+         * Handler for native token transfer operations on EVM chains.
+         *
+         * Transfers the specified amount of native tokens from the caller's wallet to the specified recipient address.
+         */
+        'native.transfer': async (params, context) => {
+            return transfer$3(params, adapter, context);
+        },
+        /**
+         * Handler for USDC transfer operations on EVM chains.
+         *
+         * Transfers the specified amount of USDC from the caller's wallet to the specified recipient address.
+         */
+        'usdc.transfer': async (params, context) => {
+            return transfer$1(params, adapter, context);
+        },
+        /**
+         * Handler for USDT transfer operations on EVM chains.
+         *
+         * Transfers the specified amount of USDT from the caller's wallet to the specified recipient address.
+         */
+        'usdt.transfer': async (params, context) => {
+            return transfer(params, adapter, context);
+        },
+        /**
+         * Handler for swap execution.
+         *
+         * Executes pre-built swap transactions from the stablecoin-service API.
+         * The service handles DEX aggregation and routing; this action handles
+         * transaction preparation and execution. Token approvals are managed
+         * separately by the provider layer.
+         */
+        'swap.execute': async (params, context) => {
+            return executeSwap(params, adapter, context);
+        },
         /**
          * Handler for CCTP v2 custom burn with hook operations on EVM chains.
          *
@@ -10444,6 +12320,44 @@ const evmPreparedChainRequestParamsSchema = zod.z.object({
         invalid_type_error: 'Arguments must be an array',
     }),
 });
+/**
+ * Zod schema for validating native token transfer parameters.
+ *
+ * This schema validates the parameters required for native token transfers
+ * (e.g., ETH on Ethereum, MATIC on Polygon):
+ * - Address must be a valid EVM address (42 characters starting with 0x)
+ * - Value must be a positive bigint greater than 0
+ *
+ * @throws KitError if validation fails
+ *
+ * @example
+ * ```typescript
+ * import { nativeTransferParamsSchema } from '@core/adapter-evm/validation'
+ *
+ * const params = {
+ *   address: '0x1234567890123456789012345678901234567890',
+ *   value: BigInt(1000000)
+ * }
+ *
+ * const result = nativeTransferParamsSchema.safeParse(params)
+ * if (result.success) {
+ *   console.log('Native transfer params are valid')
+ * } else {
+ *   console.error('Validation failed:', result.error)
+ * }
+ * ```
+ */
+const nativeTransferParamsSchema = zod.z.object({
+    address: evmAddressSchema,
+    value: zod.z
+        .bigint({
+        required_error: 'Value is required for native transfers',
+        invalid_type_error: 'Value must be a bigint',
+    })
+        .refine((val) => val > BigInt(0), {
+        message: 'Value must be greater than 0',
+    }),
+});
 /**
  * Zod schema for validating Ethereum transaction hashes.
  *
@@ -10588,6 +12502,44 @@ function assertEvmTransactionHash(txHash) {
     validate(txHash, evmTransactionHashSchema, 'Transaction hash');
 }
 
+const assertNativeTransferParamsSymbol = Symbol('assertNativeTransferParams');
+/**
+ * Asserts that the provided parameters are valid for native token transfers.
+ *
+ * The validation includes:
+ * - A valid EVM address (42 characters starting with 0x)
+ * - A positive bigint value greater than 0
+ *
+ * @param params - The parameters to validate
+ * @throws KitError with INPUT_VALIDATION_FAILED code if validation fails, with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { assertNativeTransferParams } from '@core/adapter-evm'
+ *
+ * // Valid native transfer
+ * assertNativeTransferParams({
+ *   address: '0x1234567890123456789012345678901234567890',
+ *   value: BigInt(1000000)
+ * })
+ *
+ * // This will throw KitError - invalid address
+ * assertNativeTransferParams({
+ *   address: '0x123',
+ *   value: BigInt(1000000)
+ * })
+ *
+ * // This will throw KitError - zero value
+ * assertNativeTransferParams({
+ *   address: '0x1234567890123456789012345678901234567890',
+ *   value: BigInt(0)
+ * })
+ * ```
+ */
+function assertNativeTransferParams(params) {
+    validateWithStateTracking(params, nativeTransferParamsSchema, 'Native transfer params', assertNativeTransferParamsSymbol);
+}
+
 /**
  * Asserts that the provided data matches the EIP-712 TypedData interface.
  *
@@ -11683,15 +13635,21 @@ class EthersAdapter extends EvmAdapter {
     /**
      * Simulates a contract function call using Ethers v6 `.staticCall`.
      */
-    async simulateFunctionCall(contract, functionName, args, chain) {
+    async simulateFunctionCall(contract, functionName, args, chain, overrides) {
         // Retry on allowance errors to handle RPC state propagation delays
         // (e.g., approve tx confirmed but not yet visible in latest block for staticCall)
-        const MAX_SIMULATION_ATTEMPTS = 3;
+        const MAX_SIMULATION_ATTEMPTS = 5;
         const SIMULATION_RETRY_DELAY_MS = 1000;
         for (let attempt = 1; attempt <= MAX_SIMULATION_ATTEMPTS; attempt++) {
             try {
                 const func = contract.getFunction(functionName);
-                await func.staticCall(...args);
+                // Pass overrides to staticCall so that value (ETH) is included in simulation
+                if (overrides) {
+                    await func.staticCall(...args, overrides);
+                }
+                else {
+                    await func.staticCall(...args);
+                }
                 return;
             }
             catch (err) {
@@ -11786,6 +13744,24 @@ class EthersAdapter extends EvmAdapter {
         if (!txRequest) {
             throw new Error(`Failed to populate transaction for function '${functionName}'.`);
         }
+        return this.sendTransactionWithNonceManagement(txRequest, fromAddress, chain, overrides);
+    }
+    /**
+     * Common transaction sending logic with nonce management and retry logic.
+     *
+     * This method handles the complete transaction lifecycle:
+     * - Nonce allocation and management via {@link ethersNonceManager}
+     * - Automatic retry on nonce-related errors (up to 3 attempts)
+     * - Graceful handling of user-provided nonces (no retry)
+     * - Proper error handling and wrapping
+     *
+     * @param txRequest - Populated transaction request
+     * @param fromAddress - The address sending the transaction
+     * @param chain - The chain definition for context
+     * @param overrides - Optional transaction overrides
+     * @returns Transaction hash
+     */
+    async sendTransactionWithNonceManagement(txRequest, fromAddress, chain, overrides) {
         // Chain is passed as parameter to avoid race conditions in concurrent requests
         const provider = await this.getProvider(chain);
         if (!fromAddress) {
@@ -11942,9 +13918,18 @@ class EthersAdapter extends EvmAdapter {
      * ```
      */
     async prepare(params, ctx) {
-        // Runtime validation for JavaScript consumers who lack TypeScript's compile-time checks
-        assertEvmPreparedChainRequestParams(params);
-        const { abi, functionName, args } = params;
+        const { address, abi, functionName, args, value } = params;
+        // Detect native transfer early: no abi, no functionName, no args, but has value
+        const isNativeTransfer = !abi && !functionName && !args && value !== undefined;
+        // Validate parameters based on transfer type
+        if (isNativeTransfer) {
+            // For native transfers, validate address and value
+            assertNativeTransferParams({ address, value });
+        }
+        else {
+            // For contract calls, use full validation
+            assertEvmPreparedChainRequestParams(params);
+        }
         // First, resolve the target chain from the operation context
         const targetChain = resolveChainIdentifier(ctx.chain);
         if (targetChain.type !== 'evm') {
@@ -11967,6 +13952,10 @@ class EthersAdapter extends EvmAdapter {
         if (!resolvedContext) {
             throw new Error('OperationContext resolution failed. Ensure the adapter has capabilities configured.');
         }
+        // Handle native transfers separately (after context resolution)
+        if (isNativeTransfer) {
+            return this.prepareNativeTransfer(address, value, targetChain, resolvedContext.address);
+        }
         const signer = this.getSigner();
         const contract = this.createContractInstance(params, signer, resolvedContext.address, provider);
         return {
@@ -11977,18 +13966,33 @@ class EthersAdapter extends EvmAdapter {
                 // gas estimation and fee data retrieval use the correct network.
                 const estimationProvider = await this.getProvider(targetChain);
                 const contractForEstimation = contract.connect(estimationProvider);
-                return this.estimateGasForFunction(contractForEstimation, functionName, args, targetChain, overrides, fallback);
+                // Merge value from params with overrides, with overrides taking precedence
+                // Include 'from' address since connecting to a Provider (not Signer) loses
+                // the ability to infer the sender address, which would otherwise default to
+                // the zero address and cause "transfer from the zero address" errors.
+                const mergedOverrides = {
+                    from: resolvedContext.address,
+                    ...(value !== undefined && { value }),
+                    ...overrides,
+                };
+                return this.estimateGasForFunction(contractForEstimation, functionName, args, targetChain, mergedOverrides, fallback);
             },
             execute: async (overrides) => {
+                // Merge value from params with overrides, with overrides taking precedence
+                // Only add value if it's defined (exactOptionalPropertyTypes requires this pattern)
+                const mergedOverrides = {
+                    ...(value !== undefined && { value }),
+                    ...overrides,
+                };
                 // Simulate the function call to catch errors before submission
-                await this.simulateFunctionCall(contract, functionName, args, targetChain);
+                await this.simulateFunctionCall(contract, functionName, args, targetChain, mergedOverrides);
                 await this.ensureChain(targetChain);
                 // Reconnect the contract with the current signer, which is on the correct
                 // chain after `ensureChain`, to ensure the transaction is populated and
                 // sent correctly.
                 const currentSigner = this.getSigner();
                 const contractForExecution = contract.connect(currentSigner);
-                return this.executeTransaction(contractForExecution, functionName, args, resolvedContext.address, targetChain, overrides);
+                return this.executeTransaction(contractForExecution, functionName, args, resolvedContext.address, targetChain, mergedOverrides);
             },
         };
     }
@@ -12026,11 +14030,11 @@ class EthersAdapter extends EvmAdapter {
     async getAddress(chain) {
         // Prevent calling getAddress on developer-controlled adapters
         if (this.capabilities?.addressContext === 'developer-controlled') {
-            throw new Error('Cannot call getAddress() on developer-controlled adapters. Address must be provided explicitly in the operation context.');
+            throw createValidationFailedError('adapter', 'invalid-operation', 'Cannot call getAddress() on developer-controlled adapters. Address must be provided explicitly in the operation context.');
         }
         // Chain parameter should now be provided by resolveOperationContext
         if (!chain) {
-            throw new Error('Chain parameter is required for address resolution. This should be provided by the OperationContext pattern.');
+            throw createValidationFailedError('chain', 'required', 'Chain parameter is required for address resolution. This should be provided by the OperationContext pattern.');
         }
         const signer = this.getSigner();
         const address = await signer.getAddress();
@@ -12229,15 +14233,15 @@ class EthersAdapter extends EvmAdapter {
         // Get chain from required OperationContext
         const resolvedContext = await resolveOperationContext(this, ctx);
         if (!resolvedContext) {
-            throw new Error('OperationContext resolution failed. Ensure the adapter has capabilities configured.');
+            throw createValidationFailedError('context', 'resolution-failed', 'OperationContext resolution failed. Ensure the adapter has capabilities configured.');
         }
         const targetChain = resolvedContext.chain;
         if (targetChain.type !== 'evm') {
-            throw new Error(`Invalid chain type '${String(targetChain.type)}' for EthersAdapter. Expected 'evm' chain type.`);
+            throw createInvalidChainError(targetChain.name, `Invalid chain type '${String(targetChain.type)}' for EthersAdapter. Expected 'evm' chain type.`);
         }
         const signer = this.getSigner();
         if (!signer) {
-            throw new Error('No signer is configured. Please provide a signer to sign typed data.');
+            throw createValidationFailedError('signer', 'not-configured', 'No signer is configured. Please provide a signer to sign typed data.');
         }
         const types = { ...typedData.types };
         delete types['EIP712Domain'];
@@ -12294,6 +14298,93 @@ class EthersAdapter extends EvmAdapter {
             },
         };
     }
+    /**
+     * Prepares a native token transfer (ETH, MATIC, etc.) for gas estimation and execution.
+     *
+     * Native transfers are simple value transfers that don't require contract ABI or function calls.
+     * This method reuses the existing transaction execution flow but skips contract-specific logic.
+     *
+     * @param address - The recipient address for the native token transfer
+     * @param value - The amount of native tokens to send (in wei)
+     * @param targetChain - The target chain definition
+     * @param resolvedAddress - The resolved sender address from operation context
+     * @returns Prepared chain request for native transfer
+     * @throws Error when gas estimation fails without fallback
+     * @throws Error when gas price retrieval fails
+     * @throws Error when transaction execution fails
+     *
+     * @example
+     * ```typescript
+     * // Internal usage - called by prepare() when native transfer is detected
+     * const prepared = this.prepareNativeTransfer(
+     *   '0x1234567890123456789012345678901234567890',
+     *   BigInt(1000000000000000000), // 1 ETH
+     *   Ethereum,
+     *   '0xsenderAddress'
+     * );
+     * const estimate = await prepared.estimate();
+     * const txHash = await prepared.execute();
+     * ```
+     */
+    prepareNativeTransfer(address, value, targetChain, resolvedAddress) {
+        return {
+            type: 'evm',
+            estimate: async (overrides, fallback) => {
+                await this.ensureChain(targetChain);
+                const estimationProvider = await this.getProvider(targetChain);
+                let gas;
+                try {
+                    gas = await estimationProvider.estimateGas({
+                        to: address,
+                        value,
+                        from: resolvedAddress,
+                        ...overrides,
+                    });
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+                    if (fallback &&
+                        errorMessage.toLowerCase().includes('execution reverted')) {
+                        return fallback;
+                    }
+                    // Wrap gas estimation errors with structured error format
+                    throw parseBlockchainError(error, {
+                        chain: targetChain.name,
+                        operation: 'estimateGas',
+                    });
+                }
+                let gasPrice;
+                try {
+                    gasPrice = await this.fetchGasPrice(targetChain);
+                }
+                catch (error) {
+                    // Wrap gas price errors with structured error format
+                    throw parseBlockchainError(error, {
+                        chain: targetChain.name,
+                        operation: 'getGasPrice',
+                    });
+                }
+                return {
+                    gas,
+                    gasPrice,
+                    fee: (gas * gasPrice).toString(),
+                };
+            },
+            execute: async (overrides) => {
+                await this.ensureChain(targetChain);
+                // Create transaction request for native transfer
+                const txRequest = {
+                    to: address,
+                    value,
+                    ...overrides,
+                };
+                // Use common transaction sending logic with nonce management
+                const hash = await this.sendTransactionWithNonceManagement(txRequest, resolvedAddress, targetChain, overrides);
+                assertEvmTransactionHash(hash);
+                return hash;
+            },
+        };
+    }
     /**
      * Reads a contract function using Ethers v6.
      *
@@ -12309,6 +14400,64 @@ class EthersAdapter extends EvmAdapter {
         const contractFunction = contract.getFunction(functionName);
         return (await contractFunction.staticCall(...args));
     }
+    /**
+     * Get the decimal places for an ERC-20 token on an EVM chain.
+     *
+     * This method calls the `decimals()` function on the ERC-20 token contract
+     * to fetch the number of decimal places. Ethers v6 returns decimals as bigint,
+     * which is validated and converted to a number.
+     *
+     * @param tokenAddress - The ERC-20 token contract address
+     * @param chain - The EVM chain definition where the token is deployed
+     * @returns Promise resolving to the number of decimal places
+     * @throws Error when the contract doesn't exist, doesn't support decimals(), or returns invalid data
+     *
+     * @remarks
+     * - Ethers v6 returns decimals as bigint
+     * - Validates that decimals are within 0-255 range (ERC-20 uint8 standard)
+     * - Converts bigint to number for consistent API
+     *
+     * @example
+     * ```typescript
+     * import { EthersAdapter } from '@circle-fin/adapter-ethers-v6'
+     * import { Ethereum } from '@core/chains'
+     *
+     * const adapter = new EthersAdapter({ signer })
+     *
+     * // Fetch decimals for DAI token
+     * const decimals = await adapter.getTokenDecimals(
+     *   '0x6B175474E89094C44Da98b954EedeAC495271d0F',
+     *   Ethereum
+     * )
+     * console.log(decimals) // 18
+     * ```
+     */
+    async getTokenDecimals(tokenAddress, chain) {
+        try {
+            // Ethers v6 returns bigint for uint8
+            const decimalsResult = await this.readContract({
+                address: tokenAddress,
+                abi: erc20Abi,
+                functionName: 'decimals',
+                args: [],
+            }, chain);
+            // Validate decimals are within valid range (0-255)
+            if (typeof decimalsResult !== 'bigint' ||
+                decimalsResult < 0n ||
+                decimalsResult > 255n) {
+                throw createValidationFailedError('decimals', decimalsResult, 'Token decimals must be a bigint between 0 and 255');
+            }
+            // Convert bigint to number
+            return Number(decimalsResult);
+        }
+        catch (error) {
+            // If it's already a KitError from our validation, re-throw as-is
+            if (error instanceof KitError) {
+                throw error;
+            }
+            throw createValidationFailedError('tokenAddress', tokenAddress, `Failed to fetch decimals for token on ${chain.name}: ${getErrorMessage(error)}`);
+        }
+    }
 }
 
 /**