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

package/index.d.ts

@@ -35,7 +35,6 @@ import { TransactionInstruction, Signer, AddressLookupTableAccount } from '@sola
  */
 /**
  * Represents basic information about a currency or token.
- * @interface Currency
  * @category Types
  * @description Provides the essential properties of a cryptocurrency or token.
  * @example
@@ -67,7 +66,6 @@ interface Currency {
 }
 /**
  * Base information that all chain definitions must include.
- * @interface BaseChainDefinition
  * @category Types
  * @description Provides the common properties shared by all blockchain definitions.
  * @example
@@ -127,6 +125,11 @@ interface BaseChainDefinition {
      * @description Its presence indicates that USDC is supported.
      */
     usdcAddress: string | null;
+    /**
+     * The contract address for USDT.
+     * @description Its presence indicates that USDT is supported.
+     */
+    usdtAddress: string | null;
     /**
      * Optional CCTP configuration.
      * @description If provided, the chain supports CCTP.
@@ -168,7 +171,6 @@ interface BaseChainDefinition {
 }
 /**
  * Represents chain definitions for Ethereum Virtual Machine (EVM) compatible blockchains.
- * @interface EVMChainDefinition
  * @extends BaseChainDefinition
  * @category Types
  * @description Adds properties specific to EVM chains.
@@ -200,7 +202,6 @@ interface EVMChainDefinition extends BaseChainDefinition {
 }
 /**
  * Represents chain definitions for non-EVM blockchains.
- * @interface NonEVMChainDefinition
  * @extends BaseChainDefinition
  * @category Types
  * @description Contains properties for blockchains that do not use the EVM.
@@ -253,6 +254,7 @@ type ChainType = EVMChainDefinition['type'] | NonEVMChainDefinition['type'];
  *   rpcEndpoints: ['https://eth.example.com'],
  *   eurcAddress: null,
  *   usdcAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+ *   usdtAddress: '0xdac17f958d2ee523a2206206994597c13d831ec7',
  *   cctp: {
  *     domain: 0,
  *     contracts: {
@@ -316,17 +318,74 @@ type ChainDefinitionWithCCTPv2 = ChainDefinition & {
  * - A string literal of the blockchain value (e.g., "Ethereum")
  */
 type ChainIdentifier = ChainDefinition | Blockchain | `${Blockchain}`;
+/**
+ * Split CCTP contract configuration.
+ *
+ * Used by chains that deploy separate TokenMessenger and MessageTransmitter contracts.
+ * This is the traditional CCTP architecture used by most EVM chains.
+ *
+ * @example
+ * ```typescript
+ * const splitConfig: CCTPSplitConfig = {
+ *   type: 'split',
+ *   tokenMessenger: '0x1234567890abcdef1234567890abcdef12345678',
+ *   messageTransmitter: '0xabcdef1234567890abcdef1234567890abcdef12',
+ *   confirmations: 12
+ * }
+ * ```
+ */
 interface CCTPSplitConfig {
     type: 'split';
     tokenMessenger: string;
     messageTransmitter: string;
     confirmations: number;
 }
+/**
+ * Merged CCTP contract configuration.
+ *
+ * Used by chains that deploy a single unified CCTP contract.
+ * This simplified architecture is used by newer chain integrations.
+ *
+ * @example
+ * ```typescript
+ * const mergedConfig: CCTPMergedConfig = {
+ *   type: 'merged',
+ *   contract: '0x9876543210fedcba9876543210fedcba98765432',
+ *   confirmations: 1
+ * }
+ * ```
+ */
 interface CCTPMergedConfig {
     type: 'merged';
     contract: string;
     confirmations: number;
 }
+/**
+ * Version configuration for CCTP contracts.
+ *
+ * Defines whether the chain uses split or merged CCTP contract architecture.
+ * Split configuration uses separate TokenMessenger and MessageTransmitter contracts,
+ * while merged configuration uses a single unified contract.
+ *
+ * @example Split configuration (most EVM chains)
+ * ```typescript
+ * const splitConfig: VersionConfig = {
+ *   type: 'split',
+ *   tokenMessenger: '0x1234567890abcdef1234567890abcdef12345678',
+ *   messageTransmitter: '0xabcdef1234567890abcdef1234567890abcdef12',
+ *   confirmations: 12
+ * }
+ * ```
+ *
+ * @example Merged configuration (newer chains)
+ * ```typescript
+ * const mergedConfig: VersionConfig = {
+ *   type: 'merged',
+ *   contract: '0x9876543210fedcba9876543210fedcba98765432',
+ *   confirmations: 1
+ * }
+ * ```
+ */
 type VersionConfig = CCTPSplitConfig | CCTPMergedConfig;
 type CCTPContracts = Partial<{
     v1: VersionConfig;
@@ -336,7 +395,6 @@ type CCTPContracts = Partial<{
 }>;
 /**
  * Configuration for the Cross-Chain Transfer Protocol (CCTP).
- * @interface CCTPConfig
  * @category Types
  * @description Contains the domain and required contract addresses for CCTP support.
  * @example
@@ -359,6 +417,22 @@ interface CCTPConfig {
      * The contracts required for CCTP.
      */
     contracts: CCTPContracts;
+    /**
+     * Indicates whether the chain supports forwarder for source and destination.
+     * @example
+     * ```typescript
+     * const chainWithForwarderSupported: ChainDefinition = {
+     *   forwarderSupported: {
+     *     source: true,
+     *     destination: true,
+     *   },
+     * }
+     * ```
+     */
+    forwarderSupported: {
+        source: boolean;
+        destination: boolean;
+    };
 }
 /**
  * Available kit contract types for enhanced chain functionality.
@@ -374,7 +448,7 @@ interface CCTPConfig {
  * const invalidType: KitContractType = 'invalid' // TypeScript error
  * ```
  */
-type KitContractType = 'bridge';
+type KitContractType = 'bridge' | 'adapter';
 /**
  * Kit-specific contract addresses for enhanced chain functionality.
  *
@@ -645,8 +719,20 @@ type EvmPreparedChainRequestParams = {
 interface SolanaPreparedChainRequestParams {
     /**
      * The array of instructions to include in the transaction.
+     *
+     * @remarks
+     * Used for instruction-based transaction building. Mutually exclusive with
+     * `serializedTransaction`.
      */
-    instructions: TransactionInstruction[];
+    instructions?: TransactionInstruction[];
+    /**
+     * A pre-serialized transaction as a Uint8Array (e.g., from a service like Jupiter).
+     *
+     * @remarks
+     * Used for executing pre-built transactions from external services.
+     * The transaction may be partially signed. Mutually exclusive with `instructions`.
+     */
+    serializedTransaction?: Uint8Array;
     /**
      * Additional signers besides the Adapter's wallet (e.g. program-derived authorities).
      */
@@ -1324,6 +1410,99 @@ interface CCTPv2ActionMap {
          */
         permitParams?: PermitParams;
     };
+    /**
+     * Initiate a cross-chain USDC transfer using a custom bridge contract with hook data for CCTP forwarding.
+     *
+     * This action combines the custom bridge functionality with CCTP forwarding hookData.
+     * It uses either `bridgeWithPreapprovalAndHook` or `bridgeWithPermitAndHook` contract
+     * functions depending on whether permit parameters are provided.
+     *
+     * @remarks
+     * When CCTP forwarding is enabled with custom burn, Circle's relay infrastructure will:
+     * 1. Watch for the burn transaction with forwarding hookData
+     * 2. Fetch the attestation automatically
+     * 3. Submit the destination mint transaction on behalf of the user
+     * 4. Deduct the relay fee from the minted USDC
+     *
+     * The hookData must be formatted with the CCTP forwarding magic bytes prefix
+     * followed by version and length fields. Use the `buildForwardingHookData`
+     * utility to construct properly formatted hookData.
+     *
+     * @example
+     * ```typescript
+     * import { buildForwardingHookData } from '@core/utils'
+     * import { hasCustomContractSupport } from '@core/chains'
+     *
+     * if (hasCustomContractSupport(sourceChain, 'bridge')) {
+     *   await adapter.action('cctp.v2.customBurnWithHook', {
+     *     amount: BigInt('1000000'),
+     *     mintRecipient: '0x...',
+     *     maxFee: BigInt('50000'),
+     *     minFinalityThreshold: 1000,
+     *     fromChain: ethereum,
+     *     toChain: base,
+     *     hookData: buildForwardingHookData()
+     *   })
+     * }
+     * ```
+     */
+    customBurnWithHook: CCTPv2ActionMap['customBurn'] & {
+        /**
+         * Hex-encoded hook data for CCTP forwarding.
+         *
+         * The hookData signals to Circle's Orbit relayer that forwarding is requested.
+         * Must be formatted with the CCTP forwarding magic bytes prefix ("cctp-forward"
+         * right-padded to 24 bytes) followed by uint32 version and uint32 length fields.
+         *
+         * Use the `buildForwardingHookData` utility to construct properly formatted hookData.
+         */
+        hookData: string;
+    };
+    /**
+     * Initiate a cross-chain USDC transfer with hook data for CCTP forwarding.
+     *
+     * This action extends the standard `depositForBurn` with an additional `hookData`
+     * parameter that signals to Circle's Orbit relayer that the user wants automated
+     * attestation fetching and destination mint execution.
+     *
+     * @remarks
+     * When CCTP forwarding is enabled, Circle's relay infrastructure will:
+     * 1. Watch for the burn transaction with forwarding hookData
+     * 2. Fetch the attestation automatically
+     * 3. Submit the destination mint transaction on behalf of the user
+     * 4. Deduct the relay fee from the minted USDC
+     *
+     * The hookData must be formatted with the CCTP forwarding magic bytes prefix
+     * followed by version and length fields. Use the `buildForwardingHookData`
+     * utility to construct properly formatted hookData.
+     *
+     * @example
+     * ```typescript
+     * import { buildForwardingHookData } from '@core/utils'
+     *
+     * await adapter.action('cctp.v2.depositForBurnWithHook', {
+     *   amount: BigInt('1000000'),
+     *   mintRecipient: '0x...',
+     *   maxFee: BigInt('50000'), // Must cover burn fee + forwarding fee
+     *   minFinalityThreshold: 1000,
+     *   fromChain: ethereum,
+     *   toChain: base,
+     *   hookData: buildForwardingHookData()
+     * })
+     * ```
+     */
+    depositForBurnWithHook: CCTPv2ActionMap['depositForBurn'] & {
+        /**
+         * Hex-encoded hook data for CCTP forwarding.
+         *
+         * The hookData signals to Circle's Orbit relayer that forwarding is requested.
+         * Must be formatted with the CCTP forwarding magic bytes prefix ("cctp-forward"
+         * right-padded to 24 bytes) followed by uint32 version and uint32 length fields.
+         *
+         * Use the `buildForwardingHookData` utility to construct properly formatted hookData.
+         */
+        hookData: string;
+    };
 }
 
 /**
@@ -1350,31 +1529,443 @@ interface CCTPActionMap {
 }
 
 /**
- * Action map for native token operations (ETH, SOL, MATIC, etc.).
+ * Permit signature standards for gasless token approvals.
  *
- * Native tokens are the primary currency of each blockchain network,
- * used for paying transaction fees and as a store of value.
- * These actions operate on the native token without requiring
- * a separate token contract address.
+ * Defines the permit types that can be used to approve token spending
+ * without requiring a separate approval transaction.
  *
  * @remarks
- * Native token operations differ from ERC-20/SPL token operations
- * in that they don't require contract interactions for basic transfers
- * and balance checks.
+ * - NONE: No permit, tokens must be pre-approved via separate transaction
+ * - EIP2612: Standard ERC-20 permit (USDC, DAI v2, and most modern tokens)
+ */
+declare enum PermitType {
+    /** No permit required - tokens must be pre-approved */
+    NONE = 0,
+    /** EIP-2612 standard permit */
+    EIP2612 = 1
+}
+/**
+ * Token input with permit signature for gasless approval.
+ *
+ * The Adapter Contract uses this to pull tokens from the user's wallet
+ * using permit signatures instead of requiring separate approval transactions.
  *
- * @see {@link ActionMap} for the complete action structure
+ * @example
+ * ```typescript
+ * const tokenInput: TokenInput = {
+ *   permitType: PermitType.EIP2612,
+ *   token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
+ *   from: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
+ *   amount: 1000000n, // 1 USDC
+ *   permitCalldata: '0x...' // Encoded permit(value, deadline, v, r, s)
+ * }
+ * ```
  */
-interface NativeActionMap {
+interface TokenInput {
     /**
-     * Get the native token balance (SOL, ETH, etc.) for a wallet address.
+     * Type of permit to execute.
      */
-    balanceOf: ActionParameters & {
-        /**
-         * The address to check the native balance for. If not provided, it will be
-         * automatically derived from the adapter context.
-         */
-        walletAddress?: string | undefined;
-    };
+    permitType: PermitType;
+    /**
+     * Token contract address to pull from user.
+     */
+    token: `0x${string}`;
+    /**
+     * Amount of tokens to pull via permit.
+     */
+    amount: bigint;
+    /**
+     * ABI-encoded permit calldata.
+     *
+     * For EIP-2612: encode(value, deadline, v, r, s)
+     * For Permit2: encode(permit, signature)
+     *
+     * @example '0x0000000000000000000000000000000000000000000000000000000000989680...'
+     */
+    permitCalldata: `0x${string}`;
+}
+/**
+ * Single instruction to execute within the Adapter Contract.
+ *
+ * Each instruction represents a contract call (swap, fee collection, etc.)
+ * with pre-execution approval and post-execution validation.
+ *
+ * @example
+ * ```typescript
+ * const swapInstruction: Instruction = {
+ *   target: '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE', // LiFi Diamond
+ *   data: '0x...',  // LiFi swap calldata
+ *   value: 0n,
+ *   tokenIn: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
+ *   amountToApprove: 1000000000n, // 1000 USDC to approve
+ *   tokenOut: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDT
+ *   minTokenOut: 995000000n // 995 USDT minimum (0.5% slippage)
+ * }
+ * ```
+ */
+interface Instruction {
+    /**
+     * Target contract address to call.
+     *
+     * Can be a DEX router, fee taker contract, or token contract.
+     */
+    target: `0x${string}`;
+    /**
+     * ABI-encoded calldata for the target contract.
+     */
+    data: `0x${string}`;
+    /**
+     * ETH value to send with the call (for native token operations).
+     *
+     * @defaultValue 0n
+     */
+    value: bigint;
+    /**
+     * Token to approve to target before executing instruction.
+     *
+     * Set to zero address (0x00...00) to disable pre-approval.
+     */
+    tokenIn: `0x${string}`;
+    /**
+     * Amount of tokenIn to approve to target before executing instruction.
+     *
+     * @remarks
+     * Field name matches the adapter contract's `amountToApprove` parameter exactly.
+     *
+     * @defaultValue 0n if tokenIn is zero address
+     */
+    amountToApprove: bigint;
+    /**
+     * Token to validate minimum balance after instruction.
+     *
+     * Set to zero address (0x00...00) to disable post-validation.
+     */
+    tokenOut: `0x${string}`;
+    /**
+     * Minimum required balance of tokenOut after instruction.
+     *
+     * @defaultValue 0n if tokenOut is zero address
+     */
+    minTokenOut: bigint;
+}
+/**
+ * Token recipient for residual sweep.
+ *
+ * After all instructions complete, the Adapter Contract sweeps
+ * any remaining balances to the specified beneficiaries.
+ */
+interface TokenRecipient {
+    /**
+     * Token contract address to sweep.
+     */
+    token: `0x${string}`;
+    /**
+     * Address to receive swept tokens.
+     */
+    beneficiary: `0x${string}`;
+}
+/**
+ * Execution parameters for the Adapter Contract.
+ *
+ * This struct is signed via EIP-712 by the Circle proxy and verified
+ * on-chain to ensure the execution is authorized.
+ *
+ * @remarks
+ * The executeParams are provided by the stablecoin-service and must be
+ * passed to the Adapter Contract exactly as received (no modification).
+ *
+ * @example
+ * ```typescript
+ * const executeParams: ExecuteParams = {
+ *   instructions: [
+ *     { target: dexRouter, data: swapCalldata, ... }
+ *   ],
+ *   tokens: [
+ *     { token: USDC, beneficiary: userAddress },
+ *     { token: USDT, beneficiary: userAddress }
+ *   ],
+ *   execId: 123456789n,
+ *   deadline: BigInt(Math.floor(Date.now() / 1000) + 1800),
+ *   metadata: '0x'
+ * }
+ * ```
+ */
+interface ExecuteParams {
+    /**
+     * Array of instructions to execute sequentially.
+     *
+     * Each instruction can be a swap, fee collection, or other contract call.
+     */
+    instructions: Instruction[];
+    /**
+     * Token recipients for residual sweep.
+     *
+     * Typically a 2-tuple: [tokenIn recipient, tokenOut recipient]
+     */
+    tokens: TokenRecipient[];
+    /**
+     * Unique execution identifier for replay protection.
+     *
+     * Must be globally unique and is marked as used after execution.
+     */
+    execId: bigint;
+    /**
+     * Execution deadline timestamp (Unix seconds).
+     *
+     * Transaction reverts if block.timestamp is greater than deadline.
+     */
+    deadline: bigint;
+    /**
+     * Optional metadata for tracking and analytics.
+     */
+    metadata: `0x${string}`;
+}
+/**
+ * Parameters for executing a swap transaction via the Adapter smart contract.
+ *
+ * This action executes swap transactions through the Adapter Contract, which
+ * handles token approvals via permits (EIP-2612, Permit2, etc.) and executes
+ * multi-step swap instructions atomically on-chain.
+ *
+ * @remarks
+ * The swap flow uses the Adapter Contract pattern:
+ * 1. Service provides `executeParams` and `signature` (proxy-signed EIP-712)
+ * 2. SDK builds `tokenInputs` with permit signatures for gasless approvals
+ * 3. SDK calls AdapterContract.execute(executeParams, tokenInputs, signature)
+ * 4. Adapter Contract pulls tokens via permits, executes swaps, validates outputs
+ *
+ * This enables:
+ * - Single atomic transaction (permit + swap in one tx)
+ * - Gasless approvals via EIP-2612/Permit2
+ * - Slippage protection enforced on-chain
+ * - Multi-step instructions (swap + fees) atomically
+ *
+ * **Permit Support**: The SDK constructs `TokenInput` with `permitCalldata`
+ * containing the encoded permit signature. The Adapter Contract executes
+ * the permit on-chain before pulling tokens.
+ *
+ * @example
+ * ```typescript
+ * import type { ExecuteSwapParams } from '@core/adapter'
+ * import { createSwap } from '@core/service-client'
+ * import { PermitType } from '@core/adapter'
+ *
+ * // Get swap transaction from service
+ * const swapResponse = await createSwap({
+ *   tokenInAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *   tokenOutAddress: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
+ *   tokenInChain: 'Ethereum',
+ *   fromAddress: '0x...',
+ *   toAddress: '0x...',
+ *   amount: '1000000',
+ *   apiKey: 'KIT_KEY:...',
+ * })
+ *
+ * // Build token inputs with permit
+ * const tokenInputs: TokenInput[] = [{
+ *   permitType: PermitType.EIP2612,
+ *   token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *   from: userAddress,
+ *   amount: 1000000n,
+ *   permitCalldata: '0x...' // Encoded permit signature
+ * }]
+ *
+ * // Prepare action parameters
+ * const params: ExecuteSwapParams = {
+ *   executeParams: swapResponse.transaction.executeParams,
+ *   tokenInputs,
+ *   signature: swapResponse.transaction.signature,
+ *   inputAmount: BigInt(swapResponse.amount),
+ *   tokenInAddress: swapResponse.tokenInAddress as `0x${string}`
+ * }
+ * ```
+ */
+interface ExecuteSwapEVMParams extends ActionParameters {
+    /**
+     * Execution parameters from the stablecoin-service.
+     *
+     * Contains instructions, token recipients, execution ID, deadline, and metadata.
+     * This is an EIP-712 signed struct that the Adapter Contract validates.
+     *
+     * Provided by the service - do not modify.
+     */
+    executeParams: ExecuteParams;
+    /**
+     * Token inputs with permit signatures for gasless approvals.
+     *
+     * The SDK constructs this array with permit data for each token that needs
+     * to be pulled from the user's wallet. The Adapter Contract executes these
+     * permits on-chain before executing swap instructions.
+     *
+     * @remarks
+     * For EIP-2612 permits, the SDK must:
+     * 1. Build typed data with token, spender (Adapter), amount, nonce, deadline
+     * 2. Get user signature via `adapter.signTypedData()`
+     * 3. Encode as permitCalldata: encode(value, deadline, v, r, s)
+     *
+     * @example
+     * ```typescript
+     * [{
+     *   permitType: PermitType.EIP2612,
+     *   token: '0xUSDC',
+     *   from: userAddress,
+     *   amount: 1000000n,
+     *   permitCalldata: '0x...'
+     * }]
+     * ```
+     */
+    tokenInputs: TokenInput[];
+    /**
+     * EIP-712 signature from the Circle proxy service.
+     *
+     * The service signs the executeParams to authorize the execution.
+     * The Adapter Contract verifies this signature on-chain.
+     *
+     * Provided by the service - do not modify.
+     */
+    signature: `0x${string}`;
+    /**
+     * Swap input amount in base units.
+     *
+     * @remarks
+     * The amount of tokens being swapped, provided in the token's base units (e.g., wei for ETH,
+     * smallest denomination for ERC20 tokens). This value should be extracted from the service
+     * response, as it represents the authoritative swap amount for the operation.
+     *
+     * For native currency swaps (ETH → USDC), this amount is sent as the transaction `value`.
+     * For ERC20 swaps (USDC → USDT), this amount determines the permit or approval quantity.
+     *
+     * @see CreateSwapResponse.amount - Service response field containing this value
+     *
+     * @example
+     * ```typescript
+     * import { createSwap } from '@core/service-client'
+     *
+     * // Get swap transaction from service
+     * const response = await createSwap({
+     *   tokenInAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+     *   amount: '1000000', // 1 USDC (6 decimals)
+     *   ...
+     * })
+     *
+     * // Prepare swap execution using service response amount
+     * await adapter.prepareAction('swap.execute', {
+     *   executeParams: response.transaction.executeParams,
+     *   tokenInputs,
+     *   signature: response.transaction.signature,
+     *   inputAmount: BigInt(response.amount),
+     *   tokenInAddress: response.tokenInAddress,
+     * }, context)
+     * ```
+     */
+    inputAmount: bigint;
+    /**
+     * Token address being swapped from.
+     *
+     * @remarks
+     * Used to determine if the swap involves native currency (ETH, MATIC, etc.) or ERC20 tokens.
+     * When tokenInAddress is NATIVE_TOKEN_ADDRESS (0xEeee...), the inputAmount is sent as tx.value.
+     *
+     * @see CreateSwapResponse.tokenInAddress - Service response field containing this value
+     *
+     * @example '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE' for ETH
+     * @example '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' for USDC
+     */
+    tokenInAddress: `0x${string}`;
+}
+/**
+ * Parameters for executing a swap transaction on Solana.
+ *
+ * This action executes swap transactions on Solana chains by deserializing
+ * and executing a pre-built transaction provided by the stablecoin-service.
+ *
+ * @remarks
+ * Unlike EVM chains that use the Adapter Contract pattern, Solana swaps
+ * execute a fully serialized transaction provided by the service. The
+ * transaction is base64-encoded and contains all necessary instructions
+ * for the swap operation.
+ *
+ * The service handles:
+ * - DEX aggregator routing (Jupiter, etc.)
+ * - Fee collection
+ * - Slippage protection
+ * - Token account management
+ *
+ * @example
+ * ```typescript
+ * import type { ExecuteSwapSolanaParams } from '@core/adapter'
+ * import { createSwap } from '@core/service-client'
+ *
+ * // Get swap transaction from service
+ * const swapResponse = await createSwap({
+ *   tokenInAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   tokenOutAddress: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
+ *   tokenInChain: 'Solana',
+ *   fromAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
+ *   toAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
+ *   amount: '1000000',
+ *   apiKey: 'KIT_KEY:...',
+ * })
+ *
+ * // Prepare action parameters
+ * const params: ExecuteSwapSolanaParams = {
+ *   serializedTransaction: swapResponse.transaction.data
+ * }
+ * ```
+ */
+interface ExecuteSwapSolanaParams extends ActionParameters {
+    /**
+     * Base64-encoded serialized Solana transaction.
+     *
+     * This transaction is fully constructed by the stablecoin-service and
+     * contains all swap instructions, fee payments, and token account setup.
+     * The transaction must be deserialized, signed, and submitted to the network.
+     *
+     * Provided by the service - do not modify.
+     *
+     * @example 'AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQAJFQg...'
+     */
+    serializedTransaction: string;
+}
+/**
+ * Parameters accepted by the swap.execute action, supporting both EVM and Solana chains.
+ *
+ * @remarks
+ * This union type covers all chain-specific swap execution parameter interfaces
+ * currently supported by the App Kit. Extend this union to support
+ * additional blockchains as needed. Each member provides all fields required
+ * to prepare and execute a pre-built swap transaction on its respective chain.
+ *
+ * **Type Narrowing**: The correct parameter type is inferred from the chain type
+ * in the `OperationContext` passed to `adapter.prepareAction()`. Action handlers
+ * use property-based type guards (checking for `executeParams`/`tokenInputs` for EVM
+ * or `serializedTransaction` for Solana) to narrow the union type at runtime.
+ *
+ * - {@link ExecuteSwapEVMParams} - For EVM chains (has `executeParams` and `tokenInputs`)
+ * - {@link ExecuteSwapSolanaParams} - For Solana chains (has `serializedTransaction`)
+ */
+type ExecuteSwapParams = ExecuteSwapEVMParams | ExecuteSwapSolanaParams;
+/**
+ * Action map for swap operations on EVM chains.
+ *
+ * This namespace contains actions related to token swapping operations.
+ * These actions handle the execution of pre-built swap transactions from
+ * DEX aggregators and routing services.
+ *
+ * @remarks
+ * The swap namespace is designed to be extensible for future swap-related
+ * operations such as multi-hop swaps, batched swaps, or swap-and-bridge
+ * compositions.
+ */
+interface SwapActionMap {
+    /**
+     * Execute a pre-built swap transaction.
+     *
+     * This action prepares and executes swap transactions constructed by the
+     * stablecoin-service API. It accepts transaction parameters (to, data, value)
+     * and returns a prepared chain request suitable for gas estimation or execution.
+     */
+    readonly execute: ExecuteSwapParams;
 }
 
 interface TokenActionMap {
@@ -1589,6 +2180,81 @@ interface USDCActionMap {
     balanceOf: Omit<BaseUSDCActions['balanceOf'], 'tokenAddress'>;
 }
 
+/**
+ * USDT-specific operations that automatically resolve the token address.
+ *
+ * These include standard ERC20 operations. The interface provides the same core
+ * operations as {@link TokenActionMap} but without requiring a `tokenAddress`
+ * parameter.
+ *
+ * @example
+ * ```typescript
+ * // USDT operations (address auto-resolved)
+ * await adapter.action('usdt.transfer', {
+ *   to: '0x1234...',
+ *   amount: '1000000' // 1 USDT
+ * })
+ *
+ * // vs. general token operations (address required)
+ * await adapter.action('token.transfer', {
+ *   tokenAddress: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
+ *   to: '0x1234...',
+ *   amount: '1000000'
+ * })
+ * ```
+ */
+type BaseUSDTActions = {
+    [K in keyof TokenActionMap]: Omit<TokenActionMap[K], 'tokenAddress'>;
+};
+/**
+ * USDT action map with standard ERC20 operations.
+ *
+ * This provides standard token operations for USDT transfers.
+ */
+interface USDTActionMap {
+    /**
+     * Transfer USDT tokens directly from the wallet to another address.
+     *
+     * Automatically uses the USDT contract address for the current chain.
+     */
+    transfer: BaseUSDTActions['transfer'];
+}
+
+/**
+ * Native token-related action maps for the bridge kit.
+ *
+ * This module provides action definitions for native token operations.
+ */
+interface NativeActionMap {
+    /**
+     * Transfer native tokens directly from the wallet to another address.
+     */
+    transfer: ActionParameters & {
+        /**
+         * The chain to transfer the native tokens on.
+         */
+        chain?: ChainIdentifier;
+        /**
+         * The address to send the native tokens to.
+         */
+        to: string;
+        /**
+         * The amount of native tokens to transfer.
+         */
+        amount: bigint;
+    };
+    /**
+     * Get the native token balance (SOL, ETH, etc.) for a wallet address.
+     */
+    balanceOf: ActionParameters & {
+        /**
+         * The address to check the native balance for. If not provided, it will be
+         * automatically derived from the adapter context.
+         */
+        walletAddress?: string | undefined;
+    };
+}
+
 /**
  * Central registry of all available action namespaces and their operations.
  *
@@ -1608,12 +2274,16 @@ interface USDCActionMap {
 interface ActionMap {
     /** CCTP-specific operations with automatic address resolution. */
     readonly cctp: CCTPActionMap;
-    /** Native token operations (ETH, SOL, MATIC, etc.). */
-    readonly native: NativeActionMap;
     /** General token operations requiring explicit token addresses. */
     readonly token: TokenActionMap;
     /** USDC-specific operations with automatic address resolution. */
     readonly usdc: USDCActionMap;
+    /** USDT-specific operations with automatic address resolution. */
+    readonly usdt: USDTActionMap;
+    /** Native token operations. */
+    readonly native: NativeActionMap;
+    /** Swap operations for DEX aggregator integrations. */
+    readonly swap: SwapActionMap;
 }
 /**
  * Determine if a type represents an action parameter object (leaf node).
@@ -1752,7 +2422,7 @@ type ActionHandler<TActionKey extends ActionKeys> = (params: ActionPayload<TActi
  * This type defines a registry object where each key is a valid action key
  * (as defined by {@link ActionKeys}) and each value is an {@link ActionHandler}
  * capable of processing the payload for that action. This enables strongly-typed
- * handler registration and lookup for all supported actions in the Stablecoin Kits.
+ * handler registration and lookup for all supported actions in the App Kits.
  *
  * @remarks
  * Each handler is typed as {@link ActionHandler}, which means the handler
@@ -2014,11 +2684,11 @@ interface AdapterCapabilities {
 /**
  * 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.
@@ -2279,6 +2949,134 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * @returns A promise that resolves to the total transaction fee as a bigint.
      */
     abstract calculateTransactionFee(baseComputeUnits: bigint, bufferBasisPoints: bigint | undefined, chain: ChainDefinition): Promise<EstimatedGas>;
+    /**
+     * Get the decimal places for a token address on a given chain.
+     *
+     * This method fetches the number of decimal places from a token contract.
+     * Different chain types implement this differently:
+     * - EVM: Calls the `decimals()` function on ERC-20 contracts
+     * - Solana: Reads the `decimals` field from the SPL token mint account
+     *
+     * @param tokenAddress - The token contract address (EVM) or mint address (Solana)
+     * @param chain - The chain definition where the token is deployed
+     * @returns Promise resolving to the number of decimal places for the token
+     * @throws Error when the token contract doesn't exist or decimals cannot be fetched
+     *
+     * @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
+     * ```
+     */
+    abstract getTokenDecimals(tokenAddress: string, chain: ChainDefinition): Promise<number>;
+}
+
+/**
+ * Module augmentation to register known token symbols.
+ *
+ * @remarks
+ * This file augments the `TokenSymbolRegistry` interface to provide
+ * type-safe autocomplete for built-in tokens.
+ *
+ * When imported, TypeScript will recognize 'USDC' as a valid
+ * `TokenSymbol` value with autocomplete support.
+ *
+ * Other packages or applications can create their own augmentations
+ * to add additional tokens.
+ *
+ * @example
+ * ```typescript
+ * import '@core/tokens' // Automatically includes this augmentation
+ *
+ * const symbol: TokenSymbol = 'USDC' // ✓ Autocomplete shows USDC
+ * ```
+ */
+declare module './types' {
+    /**
+     * Module augmentation: Adds known token symbols as valid keys
+     * to the TokenSymbolRegistry interface.
+     *
+     * Keys are explicitly listed to ensure IDE autocomplete works properly.
+     */
+    interface TokenSymbolRegistry {
+        USDC: true;
+        USDT: true;
+        EURC: true;
+        DAI: true;
+        USDE: true;
+        PYUSD: true;
+        WETH: true;
+        WBTC: true;
+        WSOL: true;
+        WAVAX: true;
+        WPOL: true;
+        ETH: true;
+        POL: true;
+        PLUME: true;
+        MON: true;
+    }
+}
+
+/**
+ * Module augmentation to register Blockchain enum values as ChainIdentifiers.
+ *
+ * @remarks
+ * This file augments the `ChainRegistry` interface to provide type-safe
+ * autocomplete for all `Blockchain` enum values from `@core/chains`.
+ *
+ * When this augmentation is imported (via `@core/tokens`), TypeScript will
+ * recognize all blockchain identifiers as valid `ChainIdentifier` values
+ * with IDE autocomplete support.
+ *
+ * The `Blockchain` enum values are converted to their string representations,
+ * enabling both enum values and string literals to be accepted as chain identifiers.
+ *
+ * @example
+ * ```typescript
+ * import { Blockchain } from '@core/chains'
+ * import type { ChainIdentifier } from '@core/tokens'
+ *
+ * // Using enum value
+ * const chain1: ChainIdentifier = Blockchain.Ethereum
+ *
+ * // Using string literal (with autocomplete!)
+ * const chain2: ChainIdentifier = 'Base'
+ *
+ * // Arbitrary strings also work (escape hatch for custom chains)
+ * const chain3: ChainIdentifier = 'my-custom-chain'
+ * ```
+ */
+
+declare module './types' {
+    /**
+     * Module augmentation: Adds all Blockchain enum values as valid keys
+     * to the ChainRegistry interface for type-safe chain identifier support.
+     *
+     * This ensures both enum property access (e.g., Blockchain.Ethereum) and plain
+     * string literals (e.g., 'Ethereum') are accepted by TypeScript as chain keys,
+     * providing robust autocomplete and error checking.
+     *
+     * NOTE:
+     * - This interface intentionally has no body. It merges a mapped Record type
+     *   into ChainRegistry solely for type augmentation.
+     * - This empty-body construct is a necessary TypeScript idiom for module
+     *   augmentation with Record types—directly listing mapped keys is not
+     *   feasible in interface extensions.
+     *
+     * eslint-disable-next-line directives below suppress linter complaints about
+     * the empty interface/mapping, which are benign and required for this pattern.
+     */
+    interface ChainRegistry extends Record<`${Blockchain}`, true> {
+    }
 }
 
 /**
@@ -2725,18 +3523,65 @@ interface EIP2612Options extends Record<string, unknown> {
     /** Optional deadline - will default to 1 hour from now if not provided */
     deadline?: bigint;
 }
+/**
+ * Minimal adapter interface for EIP-2612 nonce fetching.
+ *
+ * @remarks
+ * This interface represents the minimal contract an adapter must fulfill to
+ * work with `buildEIP2612TypedData`. It's intentionally minimal - only requiring
+ * nonce fetching capability. Signing is handled separately via the adapter's
+ * `signTypedData` method.
+ *
+ * This enables separation of concerns: nonce fetching (read operation) is
+ * independent from signing (write operation).
+ *
+ * @example
+ * ```typescript
+ * import type { EIP2612Adapter } from '@core/adapter-evm'
+ *
+ * // An adapter that implements the minimal interface
+ * class MyAdapter implements EIP2612Adapter {
+ *   async fetchEIP2612Nonce(
+ *     tokenAddress: `0x${string}`,
+ *     ownerAddress: `0x${string}`,
+ *     ctx: OperationContext
+ *   ): Promise<bigint> {
+ *     // Query token contract for nonce
+ *     return await this.readContract({
+ *       address: tokenAddress,
+ *       abi: [{ name: 'nonces', type: 'function', inputs: [...], outputs: [...] }],
+ *       functionName: 'nonces',
+ *       args: [ownerAddress]
+ *     })
+ *   }
+ * }
+ * ```
+ */
+interface EIP2612Adapter {
+    /**
+     * Fetch the current nonce for EIP-2612 permit signatures.
+     *
+     * Queries the token contract's `nonces(address owner)` function to get
+     * the current nonce value for permit signatures.
+     *
+     * @param tokenAddress - The token contract address
+     * @param ownerAddress - The token owner's address
+     * @param ctx - Operation context containing chain and address information
+     * @returns Promise resolving to the current nonce
+     * @throws Error when the contract call fails or token doesn't support EIP-2612
+     */
+    fetchEIP2612Nonce(tokenAddress: `0x${string}`, ownerAddress: `0x${string}`, ctx: OperationContext): Promise<bigint>;
+}
 /**
  * Function type for fetching nonces from EIP-2612 compatible tokens.
  *
- * @param owner - Token owner address
+ * This type will be deprecated, use {@link EIP2612Adapter} interface instead for better type safety
  * @param token - Token contract address
+ * @param owner - Token owner address
  * @returns Promise resolving to current nonce
  */
 type EIP2612NonceFetcher = (token: `0x${string}`, owner: `0x${string}`) => Promise<bigint>;
 
-interface EIP2612Adapter {
-    fetchEIP2612Nonce(tokenAddress: `0x${string}`, ownerAddress: `0x${string}`, ctx: OperationContext): Promise<bigint>;
-}
 /**
  * Build EIP-2612 typed data for permit signing.
  *
@@ -2994,6 +3839,22 @@ declare class EthersAdapter<TAdapterCapabilities extends AdapterCapabilities = A
      * @throws When transaction execution fails after retry attempts.
      */
     private executeTransaction;
+    /**
+     * 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
+     */
+    private sendTransactionWithNonceManagement;
     /**
      * Prepares a contract function call for gas estimation and execution with OperationContext.
      *
@@ -3296,6 +4157,35 @@ declare class EthersAdapter<TAdapterCapabilities extends AdapterCapabilities = A
      * @returns A prepared chain request for read-only function execution.
      */
     private handleReadOnlyFunction;
+    /**
+     * 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();
+     * ```
+     */
+    private prepareNativeTransfer;
     /**
      * Reads a contract function using Ethers v6.
      *
@@ -3305,6 +4195,39 @@ declare class EthersAdapter<TAdapterCapabilities extends AdapterCapabilities = A
      * @throws Error when contract read fails.
      */
     readContract<TReturnType = unknown>(params: ReadContractParams, chain: EVMChainDefinition): Promise<TReturnType>;
+    /**
+     * 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
+     * ```
+     */
+    getTokenDecimals(tokenAddress: string, chain: EVMChainDefinition): Promise<number>;
 }
 
 /**