@circle-fin/provider-cctp-v2 1.4.0 → 1.5.0

package/index.d.ts

@@ -33,7 +33,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
@@ -65,7 +64,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
@@ -125,6 +123,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.
@@ -166,7 +169,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.
@@ -198,7 +200,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.
@@ -251,6 +252,7 @@ type ChainType = EVMChainDefinition['type'] | NonEVMChainDefinition['type'];
  *   rpcEndpoints: ['https://eth.example.com'],
  *   eurcAddress: null,
  *   usdcAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+ *   usdtAddress: '0xdac17f958d2ee523a2206206994597c13d831ec7',
  *   cctp: {
  *     domain: 0,
  *     contracts: {
@@ -314,17 +316,74 @@ type ChainDefinitionWithCCTPv2 = ChainDefinition & {
  * - A string literal of the blockchain value (e.g., "Ethereum")
  */
 type ChainIdentifier$1 = 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;
@@ -334,7 +393,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
@@ -388,7 +446,7 @@ interface CCTPConfig {
  * const invalidType: KitContractType = 'invalid' // TypeScript error
  * ```
  */
-type KitContractType = 'bridge';
+type KitContractType = 'bridge' | 'adapter';
 /**
  * Kit-specific contract addresses for enhanced chain functionality.
  *
@@ -441,6 +499,8 @@ declare enum Blockchain {
     Celo_Alfajores_Testnet = "Celo_Alfajores_Testnet",
     Codex = "Codex",
     Codex_Testnet = "Codex_Testnet",
+    Edge = "Edge",
+    Edge_Testnet = "Edge_Testnet",
     Ethereum = "Ethereum",
     Ethereum_Sepolia = "Ethereum_Sepolia",
     Hedera = "Hedera",
@@ -453,6 +513,8 @@ declare enum Blockchain {
     Linea_Sepolia = "Linea_Sepolia",
     Monad = "Monad",
     Monad_Testnet = "Monad_Testnet",
+    Morph = "Morph",
+    Morph_Testnet = "Morph_Testnet",
     NEAR = "NEAR",
     NEAR_Testnet = "NEAR_Testnet",
     Noble = "Noble",
@@ -659,8 +721,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[];
+    /**
+     * 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`.
      */
-    instructions: TransactionInstruction[];
+    serializedTransaction?: Uint8Array;
     /**
      * Additional signers besides the Adapter's wallet (e.g. program-derived authorities).
      */
@@ -1457,31 +1531,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.
  *
- * @see {@link ActionMap} for the complete action structure
+ * The Adapter Contract uses this to pull tokens from the user's wallet
+ * using permit signatures instead of requiring separate approval transactions.
+ *
+ * @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 {
@@ -1696,6 +2182,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$1;
+        /**
+         * 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.
  *
@@ -1715,12 +2276,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).
@@ -1859,7 +2424,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
@@ -2121,11 +2686,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.
@@ -2386,6 +2951,35 @@ 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>;
 }
 
 /**
@@ -2578,6 +3172,20 @@ declare module './types' {
      */
     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;
     }
 }
 
@@ -2755,7 +3363,8 @@ interface TokenDefinition {
      */
     readonly symbol: string;
     /**
-     * The number of decimal places for the token.
+     * The default number of decimal places for the token.
+     * Used when no chain-specific override exists in {@link chainDecimals}.
      * @example 6 for USDC, 18 for most ERC20 tokens
      */
     readonly decimals: number;
@@ -2765,6 +3374,15 @@ interface TokenDefinition {
      * Not all chains need to be present - tokens may only exist on a subset of chains.
      */
     readonly locators: Partial<ChainLocatorMap>;
+    /**
+     * Optional per-chain decimal overrides.
+     *
+     * Some tokens have different decimal places on different chains
+     * (e.g., USDe is 18 decimals on EVM but 9 decimals on Solana).
+     * When present, the value for a specific chain takes precedence
+     * over the default {@link decimals}.
+     */
+    readonly chainDecimals?: Partial<Record<ChainIdentifier, number>>;
 }
 /**
  * A raw token locator selector with explicit decimals.
@@ -2923,6 +3541,15 @@ interface TokenRegistry {
      * @throws When the token cannot be resolved (unknown symbol, missing decimals, etc.).
      */
     resolve(selector: TokenSelector, chainId: ChainIdentifier): ResolvedToken;
+    /**
+     * Resolve a token by chain-specific locator (address/program ID).
+     *
+     * @param address - The token locator to resolve.
+     * @param chainId - The chain identifier to resolve for.
+     * @returns The resolved token information.
+     * @throws When no registry token matches the locator on the chain.
+     */
+    resolveByAddress(address: string, chainId: ChainIdentifier): ResolvedToken;
     /**
      * Get a token definition by symbol.
      *
@@ -3288,7 +3915,7 @@ interface Timer {
  * ```typescript
  * // Create a scoped metrics instance
  * const appMetrics = metrics.child({
- *   service: 'stablecoin-kit',
+ *   service: 'app-kit',
  *   version: '1.0.0',
  * })
  *