@circle-fin/app-kit 1.2.1 → 1.3.0

package/index.mjs

@@ -683,6 +683,12 @@ const InputError = {
         name: 'INPUT_UNSUPPORTED_ACTION',
         type: 'INPUT',
     },
+    /** No route satisfies the slippage or minimum-output constraint */
+    SLIPPAGE_CONSTRAINT_NOT_MET: {
+        code: 1009,
+        name: 'INPUT_SLIPPAGE_CONSTRAINT_NOT_MET',
+        type: 'INPUT',
+    },
     /** General validation failure for complex validation rules */
     VALIDATION_FAILED: {
         code: 1098,
@@ -1713,6 +1719,40 @@ function normalizeTransactionDetails(txHash, explorerUrl) {
     }
     return normalized;
 }
+/**
+ * Pattern that matches on-chain revert reasons caused by slippage or
+ * price constraints. When a revert matches, the error is surfaced as
+ * {@link InputError.SLIPPAGE_CONSTRAINT_NOT_MET} (RETRYABLE) instead of
+ * a generic simulation-failed / transaction-reverted error.
+ *
+ * @internal
+ */
+const SLIPPAGE_REVERT_PATTERN = /slippage|lower than the minimum required|less than the initial balance|minimum.?output|price.?impact|stop.?limit|InsufficientOutput|InsufficientFinalBalance/i;
+/**
+ * Handle simulation / execution revert errors, distinguishing slippage
+ * constraint failures from generic reverts and simulation failures.
+ *
+ * @internal
+ */
+function handleRevertError(msg, error, context) {
+    const reason = extractRevertReason(msg, error) ?? 'Transaction reverted';
+    if (SLIPPAGE_REVERT_PATTERN.test(reason)) {
+        return new KitError({
+            ...InputError.SLIPPAGE_CONSTRAINT_NOT_MET,
+            recoverability: 'RETRYABLE',
+            message: `Transaction on ${context.chain} reverted: "${reason}". ` +
+                'Try increasing slippageBps or adjusting stopLimit.',
+            cause: { trace: { rawError: error, chain: context.chain, reason } },
+        });
+    }
+    if (/simulation failed/i.test(msg) || context.operation === 'simulation') {
+        return createSimulationFailedError(context.chain, reason, {
+            rawError: error,
+        });
+    }
+    const { txHash, explorerUrl } = normalizeTransactionDetails(context.txHash, context.explorerUrl);
+    return createTransactionRevertedError(context.chain, reason, { rawError: error }, txHash, explorerUrl);
+}
 /**
  * Parses raw blockchain errors into structured KitError instances.
  *
@@ -1793,21 +1833,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, 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
-        if (/simulation failed/i.test(msg) || context.operation === 'simulation') {
-            return createSimulationFailedError(context.chain, reason, {
-                rawError: error,
-            });
-        }
-        // 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);
+        return handleRevertError(msg, error, context);
     }
     // Pattern 3: Gas-related errors
     // Matches gas estimation failures and gas exhaustion
@@ -1832,8 +1858,12 @@ function parseBlockchainError(error, context) {
         return createNetworkConnectionError(context.chain, { rawError: error });
     }
     // Pattern 5: RPC provider errors
-    // Matches RPC endpoint errors, invalid responses, and rate limits
-    if (/rpc|invalid response|rate limit|too many requests/i.test(msg)) {
+    // Matches RPC endpoint errors, invalid responses, rate limits, and
+    // transient JSON-RPC internal errors (e.g. ethers.js "could not coalesce error").
+    // Note: "internal error" alone is too broad — contracts like USDT emit
+    // "An internal error was received" for on-chain assertion failures.
+    // We require JSON-RPC context (codes -32603/-32000) instead.
+    if (/rpc|invalid response|rate limit|too many requests|could not coalesce|no response|server error|json-rpc\s+internal|internal json-rpc|-32603|-32000/i.test(msg)) {
         return createRpcEndpointError(context.chain, { rawError: error });
     }
     // Pattern 6: Transaction size limit errors
@@ -2930,8 +2960,19 @@ function handleClientError(statusCode, serviceName, operation, error, msg, respo
                     trace: error,
                 },
             });
-        // 404 - Not found - unsupported route
+        // 404 - Not found - unsupported route OR stop-limit / slippage constraint not met
         case 404:
+            if (isSlippageConstraintFailure(responseBody)) {
+                return new KitError({
+                    ...InputError.SLIPPAGE_CONSTRAINT_NOT_MET,
+                    recoverability: 'RETRYABLE',
+                    message: `${serviceName} ${operation} failed: ${detail}. ` +
+                        'Try increasing slippageBps or adjusting stopLimit.',
+                    cause: {
+                        trace: error,
+                    },
+                });
+            }
             return new KitError({
                 ...InputError.UNSUPPORTED_ROUTE,
                 recoverability: 'FATAL',
@@ -2966,6 +3007,38 @@ function handleClientError(statusCode, serviceName, operation, error, msg, respo
             });
     }
 }
+/**
+ * Pattern that matches proxy response body text indicating the 404 was
+ * caused by a slippage / price constraint rather than a truly unsupported
+ * route. Kept case-insensitive so future proxy wording changes are tolerated.
+ *
+ * @internal
+ */
+const SLIPPAGE_BODY_PATTERN = /slippage|stop.?limit|price.?impact|minimum.?output|SLIPPAGE_CONSTRAINT_NOT_MET/i;
+/**
+ * Determine whether a 404 was caused by an unmet slippage or price
+ * constraint rather than a genuinely unsupported route.
+ *
+ * Detection relies on the proxy response body containing slippage-related
+ * language or a structured reason code. This avoids false positives that
+ * would occur if we guessed based on request parameters alone (a user
+ * can set `slippageBps` and still hit a truly unsupported route).
+ *
+ * @param responseBody - The parsed JSON body returned by the proxy
+ * @returns `true` when the 404 should be treated as a slippage constraint failure
+ * @internal
+ */
+function isSlippageConstraintFailure(responseBody) {
+    if (responseBody === undefined) {
+        return false;
+    }
+    const textsToCheck = [
+        responseBody.externalMessage,
+        responseBody.message,
+        extractDetailFromBody(responseBody),
+    ];
+    return textsToCheck.some((t) => typeof t === 'string' && SLIPPAGE_BODY_PATTERN.test(t));
+}
 /**
  * Handles HTTP 5xx server errors and maps them to appropriate KitError instances.
  *
@@ -3121,13 +3194,16 @@ function joinFieldErrors(errors) {
  * Derive a human-readable detail string from an {@link ApiErrorResponseBody}.
  *
  * Resolution order:
- * 1. `body.message` **and** `body.errors` -- when both are present the
+ * 1. `body.externalMessage` -- the user-facing string the proxy intends
+ *    consumers to display (e.g. "No route found that satisfies the
+ *    requested stop limit"). Preferred when available.
+ * 2. `body.message` **and** `body.errors` -- when both are present the
  *    top-level message is combined with the field-level detail so
  *    developers see the full picture
  *    (e.g. `"Validation error: tokenInChain: Invalid input; amount: …"`).
- * 2. `body.message` alone -- used as-is.
- * 3. `body.errors` alone -- field-level entries joined with "; ".
- * 4. `undefined` -- caller should fall back to the raw HTTP status text.
+ * 3. `body.message` alone -- used as-is.
+ * 4. `body.errors` alone -- field-level entries joined with "; ".
+ * 5. `undefined` -- caller should fall back to the raw HTTP status text.
  *
  * @param body - The parsed response body, may be undefined
  * @returns A detail string, or undefined when no useful info is available
@@ -3137,6 +3213,12 @@ function extractDetailFromBody(body) {
     if (body === undefined) {
         return undefined;
     }
+    const externalMessage = typeof body.externalMessage === 'string' && body.externalMessage.length > 0
+        ? body.externalMessage
+        : undefined;
+    if (externalMessage !== undefined) {
+        return externalMessage;
+    }
     const topMessage = typeof body.message === 'string' && body.message.length > 0
         ? body.message
         : undefined;
@@ -3334,8 +3416,9 @@ var Blockchain;
 /**
  * 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).
+ * Unlike the full {@link Blockchain} enum, SwapChain includes mainnet
+ * networks and explicitly whitelisted testnets (e.g., {@link Arc_Testnet})
+ * where adapter contracts are deployed (CCTPv2 support).
  *
  * Dynamic validation via {@link isSwapSupportedChain} ensures chains
  * automatically work when adapter contracts and supported tokens are deployed.
@@ -3380,6 +3463,8 @@ var SwapChain;
     SwapChain["XDC"] = "XDC";
     SwapChain["HyperEVM"] = "HyperEVM";
     SwapChain["Monad"] = "Monad";
+    // Testnet chains with swap support
+    SwapChain["Arc_Testnet"] = "Arc_Testnet";
 })(SwapChain || (SwapChain = {}));
 // -----------------------------------------------------------------------------
 // Bridge Chain Enum (CCTPv2 Supported Chains)
@@ -3476,6 +3561,31 @@ var BridgeChain;
     BridgeChain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
     BridgeChain["XDC_Apothem"] = "XDC_Apothem";
 })(BridgeChain || (BridgeChain = {}));
+// -----------------------------------------------------------------------------
+// Earn Chain Enum
+// -----------------------------------------------------------------------------
+/**
+ * Enumeration of blockchains that support earn (vault deposit/withdraw)
+ * operations through the Earn Kit.
+ *
+ * Currently only Ethereum mainnet is supported. Additional chains
+ * will be added as vault protocol support expands.
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@core/chains'
+ *
+ * const result = await earnKit.deposit({
+ *   from: { adapter, chain: EarnChain.Ethereum },
+ *   vaultAddress: '0x...',
+ *   amount: '100',
+ * })
+ * ```
+ */
+var EarnChain;
+(function (EarnChain) {
+    EarnChain["Ethereum"] = "Ethereum";
+})(EarnChain || (EarnChain = {}));
 
 /**
  * Helper function to define a chain with proper TypeScript typing.
@@ -3791,6 +3901,14 @@ const BRIDGE_CONTRACT_EVM_MAINNET = '0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0'
  * on EVM-compatible chains. Use this address for mainnet adapter integrations.
  */
 const ADAPTER_CONTRACT_EVM_MAINNET = '0x7FB8c7260b63934d8da38aF902f87ae6e284a845';
+/**
+ * The adapter contract address for EVM testnet networks.
+ *
+ * This contract serves as an adapter for integrating with various protocols
+ * on EVM-compatible testnet chains. Use this address for testnet adapter
+ * integrations (e.g., Arc Testnet).
+ */
+const ADAPTER_CONTRACT_EVM_TESTNET = '0xBBD70b01a1CAbc96d5b7b129Ae1AAabdf50dd40b';
 
 /**
  * Arc Testnet chain definition
@@ -3839,6 +3957,7 @@ const ArcTestnet = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+        adapter: ADAPTER_CONTRACT_EVM_TESTNET,
     },
 });
 
@@ -4529,7 +4648,7 @@ const HyperEVM = defineChain({
     },
     chainId: 999,
     isTestnet: false,
-    explorerUrl: 'https://app.hyperliquid.xyz/explorer/tx/{hash}',
+    explorerUrl: 'https://hyperevmscan.io/tx/{hash}',
     rpcEndpoints: ['https://rpc.hyperliquid.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
@@ -6494,6 +6613,41 @@ const bridgeChainIdentifierSchema = z.union([
         message: `Chain "${chainDef.name}" (${chainDef.chain}) is not supported for bridging. Only chains in the BridgeChain enum support CCTPv2 bridging.`,
     })),
 ]);
+/**
+ * Zod schema for validating earn-specific chain identifiers.
+ *
+ * Validate that the provided chain is supported for earn (vault
+ * deposit/withdraw) operations. Currently only Ethereum is
+ * supported.
+ *
+ * Accept an EarnChain enum value, a matching string literal, or
+ * a ChainDefinition for a supported chain.
+ *
+ * @example
+ * ```typescript
+ * import { earnChainIdentifierSchema } from '@core/chains'
+ * import { EarnChain, Ethereum } from '@core/chains'
+ *
+ * // Valid
+ * earnChainIdentifierSchema.parse(EarnChain.Ethereum)
+ * earnChainIdentifierSchema.parse('Ethereum')
+ * earnChainIdentifierSchema.parse(Ethereum)
+ *
+ * // Invalid (throws ZodError)
+ * earnChainIdentifierSchema.parse('Solana')
+ * ```
+ */
+z.union([
+    z.string().refine((val) => val in EarnChain, (val) => ({
+        message: `"${val}" is not a supported earn chain. ` +
+            `Supported chains: ${Object.values(EarnChain).join(', ')}`,
+    })),
+    z.nativeEnum(EarnChain),
+    chainDefinitionSchema$2.refine((chain) => chain.chain in EarnChain, (chain) => ({
+        message: `"${chain.chain}" is not a supported earn chain. ` +
+            `Supported chains: ${Object.values(EarnChain).join(', ')}`,
+    })),
+]);
 
 /**
  * @packageDocumentation
@@ -6861,18 +7015,21 @@ function getSwapOkTokenStatus(tokenIn, tokenOut, chain, tokenRegistry, okSymbols
  * A chain supports swaps if ALL conditions are met:
  * 1. Is a member of the {@link SwapChain} enum
  * 2. Has CCTPv2 support (adapter contract deployed)
- * 3. Is mainnet (not testnet)
+ *
+ * Testnets are allowed only when explicitly listed in the
+ * {@link SwapChain} enum (e.g., Arc_Testnet).
  *
  * @param chain - Chain definition to check
  * @returns true if chain supports swap operations
  *
  * @example
  * ```typescript
- * import { isSwapSupportedChain, Ethereum, Arbitrum, Sui } from '@core/chains'
+ * import { isSwapSupportedChain, Ethereum, Arbitrum, Sui, ArcTestnet } from '@core/chains'
  *
- * isSwapSupportedChain(Ethereum)  // true (has CCTPv2, mainnet)
- * isSwapSupportedChain(Arbitrum)  // true (has CCTPv2, mainnet)
- * isSwapSupportedChain(Sui)       // false (no CCTPv2 yet)
+ * isSwapSupportedChain(Ethereum)    // true  (has CCTPv2, mainnet)
+ * isSwapSupportedChain(Arbitrum)    // true  (has CCTPv2, mainnet)
+ * isSwapSupportedChain(ArcTestnet)  // true  (has CCTPv2, whitelisted testnet)
+ * isSwapSupportedChain(Sui)         // false (no CCTPv2 yet)
  * ```
  *
  * @remarks
@@ -6883,18 +7040,12 @@ function getSwapOkTokenStatus(tokenIn, tokenOut, chain, tokenRegistry, okSymbols
  * No code changes needed when new chains are added!
  */
 function isSwapSupportedChain(chain) {
-    // Must be in the SwapChain enum
     if (!(chain.chain in SwapChain)) {
         return false;
     }
-    // Must have CCTPv2 support (adapter contract)
     if (!isCCTPV2Supported(chain)) {
         return false;
     }
-    // Must be mainnet (no testnet swaps)
-    if (chain.isTestnet) {
-        return false;
-    }
     return true;
 }
 /**
@@ -6904,7 +7055,6 @@ function isSwapSupportedChain(chain) {
  * Dynamically filter chain definitions to include only those that:
  * - Are members of the {@link SwapChain} enum
  * - Have CCTPv2 support
- * - Are mainnets
  *
  * This function is pure and accepts chains as parameter to avoid
  * circular dependencies.
@@ -7508,8 +7658,15 @@ const pollApiWithValidation = async (url, method, isValidType, config = {}, body
             }
         }
     }
-    // After the loop: we're guaranteed to have a lastError
-    throw new Error(`Maximum retry attempts (${String(effectiveConfig.maxRetries)}) exceeded: ${String(lastError?.message)}`);
+    // Preserve responseBody from the last attempt so upstream parsers
+    // (e.g. parseApiError) can inspect the server's structured response.
+    const retryError = new Error(`Maximum retry attempts (${String(effectiveConfig.maxRetries)}) exceeded: ${String(lastError?.message)}`);
+    if (lastError !== undefined &&
+        'responseBody' in lastError &&
+        lastError.responseBody !== undefined) {
+        retryError.responseBody = lastError.responseBody;
+    }
+    throw retryError;
 };
 /**
  * Convenience function for making GET requests with validation.
@@ -8200,6 +8357,7 @@ const USDC = {
         // =========================================================================
         // Testnets (alphabetically sorted)
         // =========================================================================
+        [Blockchain.Arc_Testnet]: '0x3600000000000000000000000000000000000000',
         [Blockchain.Arbitrum_Sepolia]: '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
         [Blockchain.Avalanche_Fuji]: '0x5425890298aed601595a70AB815c96711a31Bc65',
         [Blockchain.Base_Sepolia]: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
@@ -8276,6 +8434,8 @@ const EURC = {
         [Blockchain.Ethereum]: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
         [Blockchain.Solana]: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
         [Blockchain.World_Chain]: '0x1C60ba0A0eD1019e8Eb035E6daF4155A5cE2380B',
+        // Testnets
+        [Blockchain.Arc_Testnet]: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
     },
 };
 
@@ -9199,8 +9359,88 @@ function buildForwardingHookData() {
     return cachedHookDataHex;
 }
 
+const DEFAULTS = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 15_000,
+    deadlineMs: undefined,
+    jitter: true,
+    isRetryable: () => true,
+};
+function resolveOptions(options) {
+    if (options === undefined)
+        return DEFAULTS;
+    return {
+        maxRetries: options.maxRetries ?? DEFAULTS.maxRetries,
+        baseDelayMs: options.baseDelayMs ?? DEFAULTS.baseDelayMs,
+        maxDelayMs: options.maxDelayMs ?? DEFAULTS.maxDelayMs,
+        deadlineMs: options.deadlineMs ?? DEFAULTS.deadlineMs,
+        jitter: options.jitter ?? DEFAULTS.jitter,
+        isRetryable: options.isRetryable ?? DEFAULTS.isRetryable,
+    };
+}
+/**
+ * Calculate exponential backoff delay with optional jitter.
+ *
+ * @param attempt - 1-indexed retry attempt number.
+ * @param config - Resolved retry configuration.
+ * @returns Delay in milliseconds.
+ */
+function calculateDelay(attempt, config) {
+    let delay = config.baseDelayMs * Math.pow(2, attempt - 1);
+    delay = Math.min(delay, config.maxDelayMs);
+    if (config.jitter) {
+        const jitterFactor = 0.75 + Math.random() * 0.5; // NOSONAR - not security-sensitive
+        delay = Math.round(delay * jitterFactor);
+    }
+    return delay;
+}
+/**
+ * Retry an async function with exponential backoff and jitter.
+ *
+ * This is a lightweight standalone utility with no `@core/runtime`
+ * dependency, suitable for use in adapters and providers that do not
+ * participate in the middleware pipeline.
+ *
+ * @typeParam T - The resolved value type.
+ * @param fn - The async function to execute (and potentially retry).
+ * @param options - Retry configuration.
+ * @returns The resolved value of `fn`.
+ * @throws The last error when all retry attempts are exhausted, or
+ *   immediately when `isRetryable` returns `false`.
+ *
+ * @example
+ * ```typescript
+ * import { retryAsync } from '@core/utils'
+ *
+ * const receipt = await retryAsync(
+ *   () => adapter.waitForTransaction(txHash, { confirmations: 1 }, chain),
+ *   { maxRetries: 3, isRetryable: (err) => isTransientRpcError(err) },
+ * )
+ * ```
+ */
+async function retryAsync(fn, options) {
+    const config = resolveOptions(options);
+    for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const pastDeadline = config.deadlineMs !== undefined && Date.now() >= config.deadlineMs;
+            const isLastAttempt = attempt >= config.maxRetries;
+            if (isLastAttempt || pastDeadline || !config.isRetryable(error)) {
+                throw error;
+            }
+            const delayMs = calculateDelay(attempt + 1, config);
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    /* istanbul ignore next: unreachable safety throw for TypeScript */
+    throw new Error('retryAsync: unreachable');
+}
+
 var name$1 = "@circle-fin/bridge-kit";
-var version$2 = "1.8.1";
+var version$2 = "1.8.2";
 var pkg$2 = {
 	name: name$1,
 	version: version$2};
@@ -12716,10 +12956,13 @@ async function executePreparedChainRequest({ name, request, adapter, chain, conf
         }
         const txHash = await request.execute();
         step.txHash = txHash;
-        const transaction = await adapter.waitForTransaction(txHash, {
-            confirmations,
-            timeout,
-        }, chain);
+        const retryOptions = {
+            isRetryable: (err) => isRetryableError$1(parseBlockchainError(err, { chain: chain.name, txHash })),
+        };
+        if (timeout !== undefined) {
+            retryOptions.deadlineMs = Date.now() + timeout;
+        }
+        const transaction = await retryAsync(async () => adapter.waitForTransaction(txHash, { confirmations, timeout }, chain), retryOptions);
         step.state = transaction.blockNumber ? 'success' : 'error';
         step.data = transaction;
         // Generate explorer URL for the step
@@ -13451,7 +13694,12 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
         return step;
     }
     try {
-        const transaction = await adapter.waitForTransaction(receipt.txHash, { confirmations: 1 }, chain);
+        const transaction = await retryAsync(async () => adapter.waitForTransaction(receipt.txHash, { confirmations: 1 }, chain), {
+            isRetryable: (err) => isRetryableError$1(parseBlockchainError(err, {
+                chain: chain.name,
+                txHash: receipt.txHash,
+            })),
+        });
         step.state = transaction.blockNumber === undefined ? 'error' : 'success';
         step.data = transaction;
         if (transaction.blockNumber === undefined) {
@@ -13467,7 +13715,7 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
     return step;
 }
 
-var version$1 = "1.6.1";
+var version$1 = "1.6.2";
 var pkg$1 = {
 	version: version$1};
 
@@ -14208,7 +14456,10 @@ async function waitForPendingTransaction(pendingStep, adapter, chain) {
             message: `Cannot wait for pending ${pendingStep.name}: no transaction hash available`,
         });
     }
-    const txReceipt = await adapter.waitForTransaction(pendingStep.txHash, undefined, chain);
+    const txHash = pendingStep.txHash;
+    const txReceipt = await retryAsync(async () => adapter.waitForTransaction(txHash, undefined, chain), {
+        isRetryable: (err) => isRetryableError$1(parseBlockchainError(err, { chain: chain.name, txHash })),
+    });
     // Check if transaction was confirmed on-chain
     if (!txReceipt.blockNumber) {
         return {
@@ -16277,732 +16528,380 @@ const createBridgeKit = (context) => {
 };
 
 var name = "@circle-fin/swap-kit";
-var version = "1.0.3";
+var version = "1.1.0";
 var pkg = {
 	name: name,
 	version: version};
 
 /**
- * Schema for validating AdapterContext.
- * Must always contain both adapter and chain explicitly.
- * Optionally includes address for developer-controlled adapters.
+ * @packageDocumentation
+ * @module StablecoinServiceSwapSchemas
+ *
+ * Zod validation schemas for Stablecoin Service Swap Provider parameters.
+ *
+ * This module defines runtime validation schemas using Zod for type-safe
+ * validation of swap requests and service responses.
  */
-const adapterContextSchema$2 = z.object({
-    adapter: adapterSchema$1,
-    chain: swapChainIdentifierSchema,
-    address: z.string().optional(),
-});
 /**
- * Schema for validating allowance strategy values.
+ * Schema for destination address (to): must be a valid EVM or Solana address.
+ * Catches obviously malformed addresses at parse time; chain-specific validation
+ * is performed in buildServiceParams.
  */
-const allowanceStrategySchema$1 = z.enum(['permit', 'approve']);
+const destinationAddressSchema = z.union([
+    evmAddressSchema,
+    solanaAddressSchema,
+]);
 /**
- * Schema for validating SwapKit custom fee configuration.
+ * Zod schema for allowance strategy.
  *
- * Supports two mutually exclusive approaches:
+ * Validates the allowance strategy for token approvals.
+ */
+const allowanceStrategySchema$1 = z.enum(['permit', 'approve'], {
+    invalid_type_error: 'allowanceStrategy must be either "permit" or "approve"',
+});
+/**
+ * Schema for validating service swap custom fee configuration.
+ *
+ * Supports SwapKit fee approaches:
  * - Percentage-based: percentageBps + recipientAddress
  * - Callback-based: amount + recipientAddress
- *
- * @remarks
- * Mutual exclusivity is validated at runtime in buildServiceParams.
- * Chain-specific address validation is performed in resolveSwapConfig.
  */
-const swapCustomFeeSchema = z
+const serviceSwapCustomFeeSchema = z
     .object({
-    /**
-     * Fee percentage in basis points (percentage approach).
-     * 100 bps = 1%, must be > 0 and <= 10000.
-     */
-    percentageBps: z.number().int().positive().max(10000),
-    /**
-     * Fee recipient address (required).
-     * Must be a valid EVM address or Solana address.
-     */
-    recipientAddress: z
-        .string()
-        .refine((value) => evmAddressSchema.safeParse(value).success ||
-        solanaAddressSchema.safeParse(value).success, {
-        message: 'recipientAddress must be a valid blockchain address: EVM (0x + 40 hex chars) or Solana (base58, 32-44 chars)',
-    }),
+    percentageBps: z.number().int().positive().max(10000).optional(),
+    amount: z.string().optional(),
+    recipientAddress: z.string().min(1).optional(),
 })
     .strict();
 /**
- * Schema for validating swap configuration options.
+ * Zod schema for swap configuration.
  *
- * Validates:
- * - allowanceStrategy: Either 'permit' or 'approve'
- * - slippageBps: Optional positive number for slippage tolerance
- * - stopLimit: Optional decimal string for minimum output
- * - customFee: Optional fee configuration
- * - kitKey: Optional string identifier
+ * Validates the optional configuration object for swap operations.
+ * Uses shared validation utilities from \@core/provider for consistency.
  */
-const swapConfigSchema = z.object({
+const serviceSwapConfigSchema = z.object({
     allowanceStrategy: allowanceStrategySchema$1.optional(),
-    slippageBps: z.number().int().min(0).optional(),
+    slippageBps: z
+        .number({
+        invalid_type_error: 'slippageBps must be a number',
+    })
+        .int('slippageBps must be an integer')
+        .min(0, 'slippageBps must be non-negative')
+        .max(10000, 'slippageBps must be at most 10000 (100%)')
+        .optional(),
     stopLimit: z
-        .string()
-        .min(1, 'Required')
-        .pipe(createDecimalStringValidator({
-        allowZero: true,
-        regexMessage: 'Stop limit must be a numeric string with dot (.) as decimal separator (e.g., "0.1", ".1", "10.5", "1000.50"), with no thousand separators or comma decimals.',
-        attributeName: 'stopLimit',
-    })(z.string()))
+        .string({
+        invalid_type_error: 'stopLimit must be a string',
+    })
+        .min(1, 'stopLimit is required when provided')
+        .regex(/^\d+$/, 'stopLimit must be an integer string in base units (e.g., "50000000" for 50 USDC with 6 decimals)')
+        .refine((val) => {
+        try {
+            return BigInt(val) > 0n;
+        }
+        catch {
+            return false;
+        }
+    }, {
+        message: 'stopLimit must be greater than 0',
+    })
+        .optional(),
+    customFee: serviceSwapCustomFeeSchema.optional(),
+    kitKey: z
+        .string({
+        invalid_type_error: 'kitKey must be a string',
+    })
+        .min(1, 'kitKey must be a non-empty string')
+        .optional(),
+    provider: z
+        .string({
+        invalid_type_error: 'provider must be a string',
+    })
+        .min(1, 'provider must be a non-empty string')
         .optional(),
-    customFee: swapCustomFeeSchema.optional(),
-    kitKey: z.string().optional(),
 });
-const EVM_ADDRESS_REGEX = /^0x[a-fA-F0-9]{40}$/;
-const SOLANA_ADDRESS_REGEX = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
-const BASE58_CHARS_REGEX = /^[1-9A-HJ-NP-Za-km-z]+$/;
 /**
- * Broad heuristic: return true when the input is composed entirely of
- * base58 characters and is at least 32 characters long (the minimum
- * length of a valid Solana address).
+ * Zod schema for adapter context.
  *
- * The caller is expected to have already excluded valid Solana
- * addresses (via {@link SOLANA_ADDRESS_REGEX}) before invoking this
- * helper, so in practice it only matches over-length base58 strings
- * (45+ chars) that are plausibly a malformed Solana address.
+ * Validates the adapter context which contains the adapter and chain.
+ *
+ * @remarks
+ * Optionally includes address for developer-controlled adapters.
  */
-function looksLikeSolanaAddress(value) {
-    return BASE58_CHARS_REGEX.test(value) && value.length >= 32;
-}
-const MAX_DISPLAY_LENGTH = 30;
-/** Truncate a value for safe inclusion in error messages. */
-function truncate(value) {
-    return value.length > MAX_DISPLAY_LENGTH
-        ? `${value.slice(0, MAX_DISPLAY_LENGTH)}...`
-        : value;
-}
+const adapterContextSchema$2 = z.object({
+    adapter: adapterSchema$1,
+    chain: chainIdentifierSchema,
+    address: z.string().optional(),
+});
 /**
- * Schema for validating swap token input.
- *
- * Accepts either:
- * - Token symbols from the supported swap token registry ('USDC', 'WETH', 'NATIVE', etc.)
- * - Token addresses (EVM: 0x..., Solana: base58)
+ * Zod schema for ServiceSwapParams.
  *
- * This allows swapping both supported tokens (by symbol or address) and
- * arbitrary tokens (by address only), as long as at least one token is
- * an "OK token" for fee collection purposes.
- *
- * @remarks
- * Uses input-shape heuristics to produce contextual error messages:
- * - Starts with `0x` — validated as EVM address
- * - Recognized symbol — accepted
- * - 32–44 base58 characters — accepted as Solana address
- * - Otherwise — reports the most likely error (unsupported symbol,
- *   malformed Solana address, or malformed EVM address)
- *
- * Runtime validation in `isOkToken` determines if the token is supported
- * for fee collection. This schema only validates the format.
- */
-let _symbolResult;
-const swapTokenSchema = z
-    .string()
-    .superRefine((value, ctx) => {
-    if (value.startsWith('0x')) {
-        if (!EVM_ADDRESS_REGEX.test(value)) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: `Invalid EVM token address format. Expected '0x' followed by 40 hexadecimal characters, but received: '${truncate(value)}'`,
-            });
-        }
-        return;
-    }
-    _symbolResult = supportedSwapTokenSchema.safeParse(value);
-    if (_symbolResult.success) {
-        return;
-    }
-    if (SOLANA_ADDRESS_REGEX.test(value)) {
-        return;
-    }
-    if (looksLikeSolanaAddress(value)) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: `Invalid Solana token address format. Expected 32-44 base58 characters, but received: '${truncate(value)}'`,
-        });
-        return;
-    }
-    ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: `Unknown token symbol '${truncate(value)}'. Supported symbols include USDC, USDT, WETH, NATIVE, and others. See SDK documentation for the full list. You can also provide a token contract address (EVM: 0x... or Solana: base58).`,
-    });
-})
-    .transform((value) => (_symbolResult?.success ? _symbolResult.data : value));
-// Amount-in validation schema - broken out to reduce type complexity
-const amountInSchema = z
-    .string()
-    .min(1, 'Required')
-    .pipe(createDecimalStringValidator({
-    allowZero: false,
-    regexMessage: AMOUNT_FORMAT_ERROR_MESSAGE,
-    attributeName: 'amountIn',
-    maxDecimals: 18,
-})(z.string()))
-    .describe('The amount of the input token to swap, expressed as a human-readable ' +
-    "decimal string in token units (e.g., '0.05' for 0.05 USDC or 0.05 ETH).");
-/**
- * Schema for validating swap parameters with chain identifiers.
- *
- * This schema validates the complete swap operation input, ensuring:
- * - Valid adapter context (adapter + chain + optional address)
- * - Valid tokenIn and tokenOut (symbols or addresses)
- * - Valid amountIn as a positive decimal string
- * - Optional valid configuration
- *
- * The schema validates amounts with up to 18 decimal places to support
- * various token standards.
+ * Validates the input parameters for swap operations including
+ * adapter context, tokens, amount, destination, and optional configuration.
  *
  * @example
  * ```typescript
- * import { swapParamsSchema } from '@circle-fin/swap-kit'
- *
- * // Using token symbols (recommended for supported tokens)
- * const paramsWithSymbols = {
- *   from: {
- *     adapter: sourceAdapter,
- *     chain: 'Ethereum'
- *   },
- *   tokenIn: 'USDC',
- *   tokenOut: 'USDT',
- *   amountIn: '100.50', // 100.50 USDC
- *   config: {
- *     slippageBps: 300,
- *     allowanceStrategy: 'permit'
- *   }
- * }
- *
- * // Using token addresses (works for any token)
- * const paramsWithAddresses = {
- *   from: {
- *     adapter: sourceAdapter,
- *     chain: 'Base'
- *   },
- *   tokenIn: '0x4200000000000000000000000000000000000006', // WETH address
- *   tokenOut: '0x532f27101965dd16442E59d40670FaF5eBB142E4', // Any token address
- *   amountIn: '0.1' // 0.1 WETH
- * }
- *
- * // Using native token alias
- * const paramsWithNative = {
- *   from: {
- *     adapter: sourceAdapter,
- *     chain: 'Ethereum'
- *   },
- *   tokenIn: 'NATIVE', // ETH on Ethereum, MATIC on Polygon, etc.
- *   tokenOut: 'USDC',
- *   amountIn: '1.5' // 1.5 ETH
- * }
+ * import { serviceSwapParamsSchema } from '@circle-fin/provider-stablecoin-service-swap'
  *
- * const result = swapParamsSchema.safeParse(paramsWithSymbols)
- * if (result.success) {
- *   console.log('Parameters are valid')
- * } else {
- *   console.error('Validation failed:', result.error)
+ * const result = serviceSwapParamsSchema.safeParse(params)
+ * if (!result.success) {
+ *   console.error('Invalid params:', result.error.issues)
  * }
  * ```
  */
-const swapParamsSchema = z.object({
+const serviceSwapParamsSchema = z.object({
     from: adapterContextSchema$2,
-    tokenIn: swapTokenSchema,
-    tokenOut: swapTokenSchema,
-    amountIn: amountInSchema,
-    config: swapConfigSchema.optional(),
+    tokenIn: z
+        .string({
+        required_error: 'tokenIn is required',
+        invalid_type_error: 'tokenIn must be a string',
+    })
+        .min(1, 'tokenIn must be a non-empty string'),
+    tokenOut: z
+        .string({
+        required_error: 'tokenOut is required',
+        invalid_type_error: 'tokenOut must be a string',
+    })
+        .min(1, 'tokenOut must be a non-empty string'),
+    amountIn: z
+        .string({
+        required_error: 'amountIn is required',
+        invalid_type_error: 'amountIn must be a string',
+    })
+        .min(1, 'amountIn is required')
+        .regex(/^\d+$/, 'amountIn must be a numeric string in base units (e.g., "1000000")'),
+    to: destinationAddressSchema,
+    config: serviceSwapConfigSchema.optional(),
 });
 /**
- * Schema for validating SwapKit custom fee policy.
- *
- * Validates the shape of CustomFeePolicy, which lets SDK consumers
- * provide custom fee calculation and fee-recipient resolution logic.
- *
- * - computeFee: required function that returns a fee as a string (or Promise<string>).
- * - resolveFeeRecipientAddress: required function that returns a recipient address as a
- *   string (or Promise<string>).
- *
- * This schema only ensures the presence and return types of the functions; it
- * does not validate their argument types.
+ * Zod schema for provider-level custom fee configuration.
  *
- * @example
- * ```typescript
- * import { customFeePolicySchema } from '@circle-fin/swap-kit'
+ * This schema validates the fee configuration for the provider constructor,
+ * where both amount and recipientAddress are required fields.
  *
- * const config = {
- *   computeFee: async () => '0.1',
- *   resolveFeeRecipientAddress: () => '0x1234567890123456789012345678901234567890',
- * }
+ * @remarks
+ * This is different from the swap-level customFee schema imported from \@core/provider,
+ * which has optional fields for per-swap fee overrides.
+ */
+z.object({
+    amount: z
+        .string({
+        required_error: 'customFee.amount is required',
+        invalid_type_error: 'customFee.amount must be a string',
+    })
+        .min(1, 'customFee.amount must be a non-empty string')
+        .regex(/^\d+$/, 'customFee.amount must be a numeric string (e.g., "1000000")')
+        .refine((val) => {
+        try {
+            return BigInt(val) > 0n;
+        }
+        catch {
+            return false;
+        }
+    }, {
+        message: 'customFee.amount must be greater than 0',
+    }),
+    recipientAddress: z
+        .string({
+        required_error: 'customFee.recipientAddress is required',
+        invalid_type_error: 'customFee.recipientAddress must be a string',
+    })
+        .min(1, 'customFee.recipientAddress must be a non-empty string'),
+});
+/**
+ * Fee amount schema for provider output.
  *
- * const result = customFeePolicySchema.safeParse(config)
- * // result.success === true
- * ```
+ * Accepts both integer strings ("1000000") and decimal strings ("0.002")
+ * because the provider formats raw base-unit amounts into human-readable
+ * decimals via `formatAmount()`.
  */
-const customFeePolicySchema = z
-    .object({
-    computeFee: z.function().returns(z.string().or(z.promise(z.string()))),
-    resolveFeeRecipientAddress: z
-        .function()
-        .returns(z.string().or(z.promise(z.string()))),
+const formattedFeeAmountSchema = z
+    .string({
+    required_error: 'fee amount is required',
+    invalid_type_error: 'fee amount must be a string',
 })
-    .strict();
-
-const assertCustomFeePolicySymbol = Symbol('assertCustomFeePolicy');
+    .min(1, 'fee amount must be a non-empty string')
+    .regex(/^\d+(\.\d+)?$/, 'fee amount must be a non-negative numeric string (e.g., "0.002" or "1000000")');
 /**
- * Assert that the provided value conforms to {@link CustomFeePolicy}.
+ * Zod schema for individual fee entry.
  *
- * This function validates the custom fee policy configuration using the
- * customFeePolicySchema. It ensures that both required functions
- * (computeFee and resolveFeeRecipientAddress) are present and have
- * the correct return types.
+ * Validates ServiceSwapFee structure. Fee amounts can be:
+ * - A valid non-negative numeric string, integer or decimal (including "0")
+ * - null (when fee information is not available)
  *
- * Throws a structured error with detailed validation messages if the
- * configuration is malformed. Uses state tracking to avoid duplicate
- * validations.
+ * @remarks
+ * Zero fee amounts are valid and represent scenarios where no fee is charged.
+ */
+const serviceSwapFeeSchema = z.object({
+    token: z
+        .string({
+        required_error: 'fee token is required',
+        invalid_type_error: 'fee token must be a string',
+    })
+        .min(1, 'fee token must be a non-empty string'),
+    amount: z.union([formattedFeeAmountSchema, z.null()]),
+    type: z.enum(['provider', 'swap', 'gas', 'developer']),
+    recipientAddress: z.string().min(1).optional(),
+});
+/**
+ * Zod schema for validating ServiceSwapResponse data.
  *
- * @param config - The custom fee policy to validate
- * @throws \{KitError\} If the policy fails validation
+ * This schema validates the estimate response from the Stablecoin Service swap API,
+ * ensuring the estimate output data is properly formatted.
+ *
+ * @remarks
+ * Aligned with CCTP provider pattern - validates only computed response data,
+ * not request parameter echoes.
  *
  * @example
  * ```typescript
- * import { assertCustomFeePolicy } from '@circle-fin/swap-kit'
- *
- * const config = {
- *   computeFee: () => '0.1',
- *   resolveFeeRecipientAddress: () => '0x1234567890123456789012345678901234567890',
- * }
+ * import { serviceSwapResponseSchema } from '@circle-fin/provider-stablecoin-service-swap'
  *
- * try {
- *   assertCustomFeePolicy(config)
- *   // If no error is thrown, `config` is a valid CustomFeePolicy
- * } catch (error) {
- *   console.error('Invalid fee policy:', error.message)
+ * const result = serviceSwapResponseSchema.safeParse(responseData)
+ * if (!result.success) {
+ *   console.error('Invalid response:', result.error.issues)
  * }
  * ```
  */
-function assertCustomFeePolicy(config) {
-    // Use validateWithStateTracking to avoid duplicate validations
-    // This will skip validation if already validated by this function
-    // validateWithStateTracking now throws KitError directly with INPUT_VALIDATION_FAILED code
-    validateWithStateTracking(config, customFeePolicySchema, 'SwapKit custom fee policy', assertCustomFeePolicySymbol);
-}
+z
+    .object({
+    stopLimit: z.object({
+        token: z
+            .string({
+            required_error: 'stopLimit.token is required',
+            invalid_type_error: 'stopLimit.token must be a string',
+        })
+            .min(1, 'stopLimit.token must be a non-empty string'),
+        amount: z
+            .string({
+            required_error: 'stopLimit.amount is required',
+            invalid_type_error: 'stopLimit.amount must be a string',
+        })
+            .min(1, 'stopLimit.amount must be a non-empty string'),
+    }, {
+        required_error: 'stopLimit is required',
+        invalid_type_error: 'stopLimit must be an object',
+    }),
+    estimatedOutput: z.object({
+        token: z
+            .string({
+            required_error: 'estimatedOutput.token is required',
+            invalid_type_error: 'estimatedOutput.token must be a string',
+        })
+            .min(1, 'estimatedOutput.token must be a non-empty string'),
+        amount: z
+            .string({
+            required_error: 'estimatedOutput.amount is required',
+            invalid_type_error: 'estimatedOutput.amount must be a string',
+        })
+            .min(1, 'estimatedOutput.amount must be a non-empty string'),
+    }, {
+        required_error: 'estimatedOutput is required',
+        invalid_type_error: 'estimatedOutput must be an object',
+    }),
+    fees: z.array(serviceSwapFeeSchema).optional(),
+})
+    .passthrough();
 
 /**
- * Symbol used to track that assertSwapParams has validated an object.
- * @internal
+ * @packageDocumentation
+ * @module StablecoinServiceSwapValidation
+ *
+ * Validation utilities for the Stablecoin Service Swap Provider.
+ *
+ * This module provides runtime validation functions and type guards
+ * to ensure swap parameters and service responses conform to expected formats.
  */
-const ASSERT_SWAP_PARAMS_SYMBOL = Symbol('assertSwapParams');
 /**
- * Assert that the provided value conforms to the SwapParams schema.
- *
- * This function validates swap parameters using the provided Zod schema
- * and tracks validation state to avoid duplicate checks. It performs
- * comprehensive validation including:
- * - Adapter context structure
- * - Token specifications
- * - Amount format and range
- * - Optional configuration values
+ * Validates ServiceSwapParams and throws an error if invalid.
  *
- * Throws a structured error with detailed validation messages if
- * any parameter is invalid.
+ * This function performs strict validation and throws a detailed error
+ * if the parameters do not conform to the expected schema. Use this for
+ * validating input parameters to swap operations.
  *
- * @typeParam T - The expected type after validation
  * @param params - The swap parameters to validate
- * @param schema - The Zod schema to validate against
- * @throws \{KitError\} If the parameters fail validation
+ * @throws \{KitError\} If validation fails, with details about validation errors
  *
  * @example
  * ```typescript
- * import { assertSwapParams, swapParamsSchema } from '@circle-fin/swap-kit'
- *
- * const params = {
- *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
- *   tokenIn: 'USDC',
- *   tokenOut: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
- *   amountIn: '100.50'
- * }
+ * import { validateServiceSwapParams } from '@circle-fin/provider-stablecoin-service-swap'
  *
  * try {
- *   assertSwapParams(params, swapParamsSchema)
- *   // Parameters are valid, proceed with swap
+ *   validateServiceSwapParams(params)
+ *   // Proceed with swap
  * } catch (error) {
- *   console.error('Invalid parameters:', error.message)
+ *   console.error('Invalid swap params:', error.message)
  * }
  * ```
  */
-function assertSwapParams(params, schema) {
-    // Use validateWithStateTracking to avoid duplicate validations
-    // This will skip validation if already validated by this function
-    // validateWithStateTracking now throws KitError directly with INPUT_VALIDATION_FAILED code
-    validateWithStateTracking(params, schema, 'swap parameters', ASSERT_SWAP_PARAMS_SYMBOL);
-}
+const validateServiceSwapParams = (params) => {
+    const result = serviceSwapParamsSchema.safeParse(params);
+    if (!result.success) {
+        const errors = result.error.issues.map((issue) => issue.message).join(', ');
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Invalid ServiceSwapParams: ${errors}.`,
+            cause: {
+                trace: { params, validationErrors: result.error.issues },
+            },
+        });
+    }
+};
 
 /**
  * @packageDocumentation
- * @module StablecoinServiceSwapSchemas
- *
- * Zod validation schemas for Stablecoin Service Swap Provider parameters.
+ * @module ServiceClientConstants
  *
- * This module defines runtime validation schemas using Zod for type-safe
- * validation of swap requests and service responses.
- */
-/**
- * Schema for destination address (to): must be a valid EVM or Solana address.
- * Catches obviously malformed addresses at parse time; chain-specific validation
- * is performed in buildServiceParams.
+ * Constants for the Stablecoin Service API.
  */
-const destinationAddressSchema = z.union([
-    evmAddressSchema,
-    solanaAddressSchema,
-]);
 /**
- * Zod schema for allowance strategy.
+ * Default configuration values for the quote fetcher.
  *
- * Validates the allowance strategy for token approvals.
- */
-const allowanceStrategySchema = z.enum(['permit', 'approve'], {
-    invalid_type_error: 'allowanceStrategy must be either "permit" or "approve"',
-});
-/**
- * Schema for validating service swap custom fee configuration.
+ * @remarks
+ * The timeout is set to 30 seconds to match the load balancer timeout.
+ * This accommodates the LiFi DEX aggregator (5s hard cap), Circle Wallets
+ * signing (~500ms p99), internal overhead (~100ms), and network latency.
  *
- * Supports SwapKit fee approaches:
- * - Percentage-based: percentageBps + recipientAddress
- * - Callback-based: amount + recipientAddress
+ * @internal
  */
-const serviceSwapCustomFeeSchema = z
-    .object({
-    percentageBps: z.number().int().positive().max(10000).optional(),
-    amount: z.string().optional(),
-    recipientAddress: z.string().min(1).optional(),
-})
-    .strict();
+const DEFAULT_CONFIG = {
+    timeout: 30_000, // 30 seconds - matches load balancer timeout
+    maxRetries: 3, // 3 retries as per requirements
+    retryDelay: 200, // 200ms between retries
+    headers: {
+        'Content-Type': 'application/json',
+    },
+};
 /**
- * Zod schema for swap configuration.
+ * Base URL for the Stablecoin Service API.
  *
- * Validates the optional configuration object for swap operations.
- * Uses shared validation utilities from \@core/provider for consistency.
+ * @internal
  */
-const serviceSwapConfigSchema = z.object({
-    allowanceStrategy: allowanceStrategySchema.optional(),
-    slippageBps: z
-        .number({
-        invalid_type_error: 'slippageBps must be a number',
-    })
-        .int('slippageBps must be an integer')
-        .min(0, 'slippageBps must be non-negative')
-        .max(10000, 'slippageBps must be at most 10000 (100%)')
-        .optional(),
-    stopLimit: z
-        .string({
-        invalid_type_error: 'stopLimit must be a string',
-    })
-        .min(1, 'stopLimit is required when provided')
-        .regex(/^\d+$/, 'stopLimit must be an integer string in base units (e.g., "50000000" for 50 USDC with 6 decimals)')
-        .refine((val) => {
-        try {
-            return BigInt(val) > 0n;
-        }
-        catch {
-            return false;
-        }
-    }, {
-        message: 'stopLimit must be greater than 0',
-    })
-        .optional(),
-    customFee: serviceSwapCustomFeeSchema.optional(),
-    kitKey: z
-        .string({
-        invalid_type_error: 'kitKey must be a string',
-    })
-        .min(1, 'kitKey must be a non-empty string')
-        .optional(),
-    provider: z
-        .string({
-        invalid_type_error: 'provider must be a string',
-    })
-        .min(1, 'provider must be a non-empty string')
-        .optional(),
-});
+const STABLECOIN_SERVICE_BASE_URL = 'https://api.circle.com';
+
 /**
- * Zod schema for adapter context.
+ * @packageDocumentation
+ * @module ServiceClientSchemas
  *
- * Validates the adapter context which contains the adapter and chain.
+ * Zod validation schemas for Stablecoin Service API parameters.
  *
- * @remarks
- * Optionally includes address for developer-controlled adapters.
+ * This module defines runtime validation schemas using Zod for type-safe
+ * validation of API requests and responses.
  */
-const adapterContextSchema$1 = z.object({
-    adapter: adapterSchema$1,
-    chain: chainIdentifierSchema,
-    address: z.string().optional(),
-});
 /**
- * Zod schema for ServiceSwapParams.
+ * Zod schema for validating stop limits.
  *
- * Validates the input parameters for swap operations including
- * adapter context, tokens, amount, destination, and optional configuration.
+ * The stop limit is the minimum acceptable token output amount expressed in
+ * base units. It must be a positive integer string.
  *
  * @example
  * ```typescript
- * import { serviceSwapParamsSchema } from '@circle-fin/provider-stablecoin-service-swap'
+ * import { stopLimitSchema } from '@core/service-client'
  *
- * const result = serviceSwapParamsSchema.safeParse(params)
+ * const result = stopLimitSchema.safeParse('1000000')
  * if (!result.success) {
- *   console.error('Invalid params:', result.error.issues)
- * }
- * ```
- */
-const serviceSwapParamsSchema = z.object({
-    from: adapterContextSchema$1,
-    tokenIn: z
-        .string({
-        required_error: 'tokenIn is required',
-        invalid_type_error: 'tokenIn must be a string',
-    })
-        .min(1, 'tokenIn must be a non-empty string'),
-    tokenOut: z
-        .string({
-        required_error: 'tokenOut is required',
-        invalid_type_error: 'tokenOut must be a string',
-    })
-        .min(1, 'tokenOut must be a non-empty string'),
-    amountIn: z
-        .string({
-        required_error: 'amountIn is required',
-        invalid_type_error: 'amountIn must be a string',
-    })
-        .min(1, 'amountIn is required')
-        .regex(/^\d+$/, 'amountIn must be a numeric string in base units (e.g., "1000000")'),
-    to: destinationAddressSchema,
-    config: serviceSwapConfigSchema.optional(),
-});
-/**
- * Zod schema for provider-level custom fee configuration.
- *
- * This schema validates the fee configuration for the provider constructor,
- * where both amount and recipientAddress are required fields.
- *
- * @remarks
- * This is different from the swap-level customFee schema imported from \@core/provider,
- * which has optional fields for per-swap fee overrides.
- */
-z.object({
-    amount: z
-        .string({
-        required_error: 'customFee.amount is required',
-        invalid_type_error: 'customFee.amount must be a string',
-    })
-        .min(1, 'customFee.amount must be a non-empty string')
-        .regex(/^\d+$/, 'customFee.amount must be a numeric string (e.g., "1000000")')
-        .refine((val) => {
-        try {
-            return BigInt(val) > 0n;
-        }
-        catch {
-            return false;
-        }
-    }, {
-        message: 'customFee.amount must be greater than 0',
-    }),
-    recipientAddress: z
-        .string({
-        required_error: 'customFee.recipientAddress is required',
-        invalid_type_error: 'customFee.recipientAddress must be a string',
-    })
-        .min(1, 'customFee.recipientAddress must be a non-empty string'),
-});
-/**
- * Fee amount schema for provider output.
- *
- * Accepts both integer strings ("1000000") and decimal strings ("0.002")
- * because the provider formats raw base-unit amounts into human-readable
- * decimals via `formatAmount()`.
- */
-const formattedFeeAmountSchema = z
-    .string({
-    required_error: 'fee amount is required',
-    invalid_type_error: 'fee amount must be a string',
-})
-    .min(1, 'fee amount must be a non-empty string')
-    .regex(/^\d+(\.\d+)?$/, 'fee amount must be a non-negative numeric string (e.g., "0.002" or "1000000")');
-/**
- * Zod schema for individual fee entry.
- *
- * Validates ServiceSwapFee structure. Fee amounts can be:
- * - A valid non-negative numeric string, integer or decimal (including "0")
- * - null (when fee information is not available)
- *
- * @remarks
- * Zero fee amounts are valid and represent scenarios where no fee is charged.
- */
-const serviceSwapFeeSchema = z.object({
-    token: z
-        .string({
-        required_error: 'fee token is required',
-        invalid_type_error: 'fee token must be a string',
-    })
-        .min(1, 'fee token must be a non-empty string'),
-    amount: z.union([formattedFeeAmountSchema, z.null()]),
-    type: z.enum(['provider', 'swap', 'gas', 'developer']),
-    recipientAddress: z.string().min(1).optional(),
-});
-/**
- * Zod schema for validating ServiceSwapResponse data.
- *
- * This schema validates the estimate response from the Stablecoin Service swap API,
- * ensuring the estimate output data is properly formatted.
- *
- * @remarks
- * Aligned with CCTP provider pattern - validates only computed response data,
- * not request parameter echoes.
- *
- * @example
- * ```typescript
- * import { serviceSwapResponseSchema } from '@circle-fin/provider-stablecoin-service-swap'
- *
- * const result = serviceSwapResponseSchema.safeParse(responseData)
- * if (!result.success) {
- *   console.error('Invalid response:', result.error.issues)
- * }
- * ```
- */
-z
-    .object({
-    stopLimit: z.object({
-        token: z
-            .string({
-            required_error: 'stopLimit.token is required',
-            invalid_type_error: 'stopLimit.token must be a string',
-        })
-            .min(1, 'stopLimit.token must be a non-empty string'),
-        amount: z
-            .string({
-            required_error: 'stopLimit.amount is required',
-            invalid_type_error: 'stopLimit.amount must be a string',
-        })
-            .min(1, 'stopLimit.amount must be a non-empty string'),
-    }, {
-        required_error: 'stopLimit is required',
-        invalid_type_error: 'stopLimit must be an object',
-    }),
-    estimatedOutput: z.object({
-        token: z
-            .string({
-            required_error: 'estimatedOutput.token is required',
-            invalid_type_error: 'estimatedOutput.token must be a string',
-        })
-            .min(1, 'estimatedOutput.token must be a non-empty string'),
-        amount: z
-            .string({
-            required_error: 'estimatedOutput.amount is required',
-            invalid_type_error: 'estimatedOutput.amount must be a string',
-        })
-            .min(1, 'estimatedOutput.amount must be a non-empty string'),
-    }, {
-        required_error: 'estimatedOutput is required',
-        invalid_type_error: 'estimatedOutput must be an object',
-    }),
-    fees: z.array(serviceSwapFeeSchema).optional(),
-})
-    .passthrough();
-
-/**
- * @packageDocumentation
- * @module StablecoinServiceSwapValidation
- *
- * Validation utilities for the Stablecoin Service Swap Provider.
- *
- * This module provides runtime validation functions and type guards
- * to ensure swap parameters and service responses conform to expected formats.
- */
-/**
- * Validates ServiceSwapParams and throws an error if invalid.
- *
- * This function performs strict validation and throws a detailed error
- * if the parameters do not conform to the expected schema. Use this for
- * validating input parameters to swap operations.
- *
- * @param params - The swap parameters to validate
- * @throws \{KitError\} If validation fails, with details about validation errors
- *
- * @example
- * ```typescript
- * import { validateServiceSwapParams } from '@circle-fin/provider-stablecoin-service-swap'
- *
- * try {
- *   validateServiceSwapParams(params)
- *   // Proceed with swap
- * } catch (error) {
- *   console.error('Invalid swap params:', error.message)
- * }
- * ```
- */
-const validateServiceSwapParams = (params) => {
-    const result = serviceSwapParamsSchema.safeParse(params);
-    if (!result.success) {
-        const errors = result.error.issues.map((issue) => issue.message).join(', ');
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: `Invalid ServiceSwapParams: ${errors}.`,
-            cause: {
-                trace: { params, validationErrors: result.error.issues },
-            },
-        });
-    }
-};
-
-/**
- * @packageDocumentation
- * @module ServiceClientConstants
- *
- * Constants for the Stablecoin Service API.
- */
-/**
- * Default configuration values for the quote fetcher.
- *
- * @remarks
- * The timeout is set to 30 seconds to match the load balancer timeout.
- * This accommodates the LiFi DEX aggregator (5s hard cap), Circle Wallets
- * signing (~500ms p99), internal overhead (~100ms), and network latency.
- *
- * @internal
- */
-const DEFAULT_CONFIG = {
-    timeout: 30_000, // 30 seconds - matches load balancer timeout
-    maxRetries: 3, // 3 retries as per requirements
-    retryDelay: 200, // 200ms between retries
-    headers: {
-        'Content-Type': 'application/json',
-    },
-};
-/**
- * Base URL for the Stablecoin Service API.
- *
- * @internal
- */
-const STABLECOIN_SERVICE_BASE_URL = 'https://api.circle.com';
-
-/**
- * @packageDocumentation
- * @module ServiceClientSchemas
- *
- * Zod validation schemas for Stablecoin Service API parameters.
- *
- * This module defines runtime validation schemas using Zod for type-safe
- * validation of API requests and responses.
- */
-/**
- * Zod schema for validating stop limits.
- *
- * The stop limit is the minimum acceptable token output amount expressed in
- * base units. It must be a positive integer string.
- *
- * @example
- * ```typescript
- * import { stopLimitSchema } from '@core/service-client'
- *
- * const result = stopLimitSchema.safeParse('1000000')
- * if (!result.success) {
- *   console.error('Validation failed:', result.error.issues)
+ *   console.error('Validation failed:', result.error.issues)
  * }
  * ```
  */
@@ -17410,6 +17309,31 @@ const createSwapParamsSchema = createSwapRequestSchema.extend({
      */
     apiKey: apiKeySchema,
 });
+/**
+ * Zod schema for validating GetSwapStatusResponse data.
+ */
+const getSwapStatusResponseSchema = z.object({
+    status: z.enum(['DONE', 'PENDING', 'NOT_FOUND', 'FAILED']),
+    amountOut: z.string().optional(),
+});
+/**
+ * Zod schema for validating GetSwapStatusParams.
+ */
+const getSwapStatusParamsSchema = z.object({
+    txHash: z
+        .string({
+        required_error: 'txHash is required',
+        invalid_type_error: 'txHash must be a string',
+    })
+        .min(1, 'txHash is required and must be a non-empty string'),
+    chain: z
+        .string({
+        required_error: 'chain is required',
+        invalid_type_error: 'chain must be a string',
+    })
+        .min(1, 'chain is required and must be a non-empty string'),
+    apiKey: apiKeySchema,
+});
 /**
  * Zod schema for validating CreateSwapResponse payloads.
  */
@@ -17585,6 +17509,27 @@ const isCreateSwapResponse = (obj) => createSwapResponseSchema.safeParse(obj).su
  * @throws If validation fails.
  */
 const parseCreateSwapResponse = (obj) => createSwapResponseSchema.parse(obj);
+/**
+ * Type guard to validate GetSwapStatusResponse objects.
+ *
+ * @param obj - The object to validate
+ * @returns True if the object is a valid GetSwapStatusResponse, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isGetSwapStatusResponse } from '@core/service-client'
+ *
+ * const response = await fetch('/v1/stablecoinKits/swap/status?...')
+ * const data = await response.json()
+ *
+ * if (isGetSwapStatusResponse(data)) {
+ *   console.log('Swap status:', data.status)
+ * } else {
+ *   console.error('Invalid response format')
+ * }
+ * ```
+ */
+const isGetSwapStatusResponse = (obj) => getSwapStatusResponseSchema.safeParse(obj).success;
 
 /**
  * @packageDocumentation
@@ -17819,6 +17764,61 @@ const getQuote = async (params) => {
     return pollApiGet(url, isGetQuoteResponse, effectiveConfig);
 };
 
+/**
+ * Build the full URL for the swap-status polling endpoint.
+ *
+ * @param params - Swap status parameters containing the transaction
+ *   hash and chain identifier.
+ * @returns Fully-qualified URL string with query parameters set.
+ *
+ * @example
+ * ```typescript
+ * import { buildSwapStatusUrl } from '@core/service-client'
+ *
+ * const url = buildSwapStatusUrl({
+ *   txHash: '0xabc123',
+ *   chain: 'Ethereum',
+ *   apiKey: 'my-api-key',
+ * })
+ * // => 'https://…/v1/stablecoinKits/swap/status?txHash=0xabc123&chain=Ethereum'
+ * ```
+ */
+const buildSwapStatusUrl = (params) => {
+    const url = new URL('/v1/stablecoinKits/swap/status', STABLECOIN_SERVICE_BASE_URL);
+    url.searchParams.set('txHash', params.txHash);
+    url.searchParams.set('chain', params.chain);
+    return url.toString();
+};
+/**
+ * Fetches the swap status from the Stablecoin Service.
+ *
+ * The proxy resolves the final swap status server-side (up to 30s) and
+ * returns a normalized response.
+ *
+ * @param params - txHash, chain, and apiKey
+ * @returns The swap status with optional amountOut when DONE
+ * @throws KitError if parameter validation fails
+ * @throws KitError if the API returns an error response
+ */
+const getSwapStatus = async (params) => {
+    const result = getSwapStatusParamsSchema.safeParse(params);
+    if (!result.success) {
+        throw convertZodErrorToStructured(result.error, {
+            txHash: params.txHash,
+            chain: params.chain,
+        });
+    }
+    const url = buildSwapStatusUrl(result.data);
+    const effectiveConfig = {
+        ...DEFAULT_CONFIG,
+        headers: {
+            ...DEFAULT_CONFIG.headers,
+            Authorization: `Bearer ${result.data.apiKey}`,
+        },
+    };
+    return pollApiGet(url, isGetSwapStatusResponse, effectiveConfig);
+};
+
 /**
  * Core type definitions for EVM-compatible blockchain transaction execution
  * and gas estimation.
@@ -19422,9 +19422,9 @@ const EIP2612_SUPPORTED_TOKENS = new Set(['USDC']);
  * cast call <USDC_ADDRESS> "version()(string)" --rpc-url <RPC_URL>
  * ```
  *
- * Only swap-supported EVM mainnet chains are included. Solana is excluded since
- * it doesn't use EIP-712 signatures. Values were verified on-chain via
- * `cast call <usdc> "name()(string)"`.
+ * All swap-supported EVM chains (mainnet and whitelisted testnets) are included.
+ * Solana is excluded since it doesn't use EIP-712 signatures. Values were
+ * verified on-chain via `cast call <usdc> "name()(string)"`.
  *
  * @internal
  */
@@ -19445,6 +19445,11 @@ const USDC_PERMIT_METADATA_BY_NAME = {
     XDC: { chainId: XDC.chainId, name: 'USDC', version: '2' },
     HyperEVM: { chainId: HyperEVM.chainId, name: 'USDC', version: '2' },
     Monad: { chainId: Monad.chainId, name: 'USDC', version: '2' },
+    Arc_Testnet: {
+        chainId: ArcTestnet.chainId,
+        name: 'USDC',
+        version: '2',
+    },
 };
 /**
  * Flatten {@link USDC_PERMIT_METADATA_BY_NAME} into a chain-ID-keyed map for O(1) lookup.
@@ -19475,7 +19480,7 @@ const USDC_PERMIT_METADATA = Object.values(USDC_PERMIT_METADATA_BY_NAME).reduce(
  * **Unsupported Scenarios**:
  * - Returns `false` for native currency (ETH, MATIC, etc.)
  * - Returns `false` for non-EVM chains (e.g., Solana)
- * - Returns `false` for chains not in USDC_PERMIT_METADATA (testnets, non-swap chains)
+ * - Returns `false` for chains not in USDC_PERMIT_METADATA (e.g. non-whitelisted testnets, non-swap chains)
  * - Returns `false` for chains without USDC deployed (`chain.usdcAddress === null`)
  * - Returns `false` for tokens not in allowlist
  *
@@ -20757,165 +20762,6 @@ async function formatTokenValue(value, token, chain, adapter) {
     }
 }
 
-const LIFI_STATUS_BASE_URL = 'https://li.quest/v1/status';
-const LIFI_SOLANA_CHAIN_ID = 1151111081099710;
-const LIFI_POLLING_CONFIG = {
-    maxRetries: 20,
-    retryDelay: 3_000,
-};
-const assertNever = (value) => {
-    throw new Error(`Unexpected LI.FI status value: ${String(value)}`);
-};
-const createRetryableLifiStatusError = (status, substatus) => {
-    return new KitError({
-        ...NetworkError.LIFI_STATUS_PENDING,
-        recoverability: 'RETRYABLE',
-        message: substatus
-            ? `LI.FI status is not ready yet: ${status} (${substatus})`
-            : `LI.FI status is not ready yet: ${status}`,
-        cause: {
-            trace: { status, ...(substatus !== undefined && { substatus }) },
-        },
-    });
-};
-const createFatalLifiStatusError = (message, trace) => {
-    return new KitError({
-        ...NetworkError.LIFI_STATUS_FAILED,
-        recoverability: 'FATAL',
-        message,
-        cause: { trace },
-    });
-};
-const hasValidReceivingStructure = (receiving) => {
-    return (receiving === undefined ||
-        (typeof receiving === 'object' &&
-            receiving !== null &&
-            (!('amount' in receiving) ||
-                typeof receiving.amount === 'string')));
-};
-const hasValidLifiStatusStructure = (obj) => {
-    return (typeof obj === 'object' &&
-        obj !== null &&
-        'status' in obj &&
-        ['NOT_FOUND', 'INVALID', 'PENDING', 'DONE', 'FAILED'].includes(String(obj.status)) &&
-        (!('substatus' in obj) ||
-            typeof obj.substatus === 'string') &&
-        hasValidReceivingStructure(obj.receiving));
-};
-const getLifiChainId = (chain) => {
-    if (chain.type === 'evm') {
-        return chain.chainId;
-    }
-    if (chain.type === 'solana') {
-        return LIFI_SOLANA_CHAIN_ID;
-    }
-    throw new KitError({
-        ...InputError.VALIDATION_FAILED,
-        recoverability: 'FATAL',
-        message: `LI.FI status polling is not supported for chain type "${chain.type}".`,
-        cause: {
-            trace: { chain: chain.name, chainType: chain.type },
-        },
-    });
-};
-const buildLifiStatusUrl = (txHash, lifiChainId) => {
-    const url = new URL(LIFI_STATUS_BASE_URL);
-    url.searchParams.set('txHash', txHash);
-    url.searchParams.set('fromChain', lifiChainId.toString());
-    url.searchParams.set('toChain', lifiChainId.toString());
-    return url.toString();
-};
-const isLifiStatusDone = (obj) => {
-    if (!hasValidLifiStatusStructure(obj)) {
-        throw new KitError({
-            ...InputError.VALIDATION_FAILED,
-            recoverability: 'FATAL',
-            message: 'Invalid LI.FI status response structure',
-            cause: { trace: obj },
-        });
-    }
-    switch (obj.status) {
-        case 'PENDING':
-        case 'NOT_FOUND':
-            throw createRetryableLifiStatusError(obj.status, obj.substatus);
-        case 'FAILED':
-        case 'INVALID':
-            throw createFatalLifiStatusError(`LI.FI status returned a terminal failure state: ${obj.status}`, {
-                status: obj.status,
-                ...(obj.substatus !== undefined && { substatus: obj.substatus }),
-            });
-        case 'DONE':
-            if (obj.substatus === 'COMPLETED') {
-                return true;
-            }
-            throw createFatalLifiStatusError(`LI.FI status returned a non-completable terminal state: DONE${obj.substatus ? ` (${obj.substatus})` : ''}`, {
-                status: obj.status,
-                ...(obj.substatus !== undefined && { substatus: obj.substatus }),
-            });
-        default:
-            return assertNever(obj.status);
-    }
-};
-const LIFI_TOTAL_TIMEOUT_MS = 90_000;
-const isLifiNotIndexedError = (error) => {
-    return error instanceof Error && error.message.includes('HTTP 400');
-};
-/**
- * Poll the LI.FI status API to retrieve the output amount for a
- * completed swap transaction. Return `undefined` on any failure
- * because the swap has already succeeded on-chain — this is
- * best-effort enrichment only.
- *
- * @param txHash - The transaction hash of the swap to look up.
- * @param chain - The chain definition where the swap was executed.
- * @returns The raw token amount string from LI.FI, or `undefined`
- *   if the status could not be retrieved.
- * @throws Never throws — all errors are caught and result in an
- *   `undefined` return value.
- *
- * @example
- * ```typescript
- * import { fetchLifiAmountOut } from '../utils'
- * import { Ethereum } from '@core/chains'
- *
- * const amountOut = await fetchLifiAmountOut('0xabc...', Ethereum)
- * if (amountOut !== undefined) {
- *   console.log('Output amount:', amountOut)
- * }
- * ```
- */
-const fetchLifiAmountOut = async (txHash, chain) => {
-    try {
-        const lifiChainId = getLifiChainId(chain);
-        const url = buildLifiStatusUrl(txHash, lifiChainId);
-        // LI.FI returns HTTP 400 before it indexes the transaction.
-        // pollApiGet treats 400 as non-retryable, so we wrap it in our
-        // own retry loop that catches the "not indexed yet" 400 and
-        // waits for LI.FI to become aware of the transaction.
-        const { maxRetries, retryDelay } = LIFI_POLLING_CONFIG;
-        const deadline = Date.now() + LIFI_TOTAL_TIMEOUT_MS;
-        for (let attempt = 1; attempt <= maxRetries; attempt++) {
-            if (Date.now() >= deadline)
-                return undefined;
-            try {
-                const response = await pollApiGet(url, isLifiStatusDone, LIFI_POLLING_CONFIG);
-                return response.receiving?.amount;
-            }
-            catch (error) {
-                if (!isLifiNotIndexedError(error) || attempt === maxRetries) {
-                    throw error;
-                }
-                await new Promise((resolve) => setTimeout(resolve, retryDelay));
-            }
-        }
-        return undefined;
-    }
-    catch {
-        // Best-effort enrichment only; the swap has already succeeded on-chain.
-        return undefined;
-    }
-};
-
 /**
  * Safety multiplier applied to locally estimated gas for EVM swap execution.
  * Derived from refund cap (max 1/5 of total gas used) plus an extra 0.1 margin,
@@ -20994,7 +20840,7 @@ function handleSwapExecutionError(err, txHash, chain) {
  * Dynamically determined based on:
  * - Membership in the SwapChain enum
  * - CCTPv2 support (adapter contract deployed)
- * - Mainnet only (no testnets)
+ * - Whitelisted chains only (testnets allowed when explicitly in SwapChain enum)
  *
  * This list automatically updates when new chains are added.
  *
@@ -21194,7 +21040,7 @@ class StablecoinServiceSwapProvider {
      *
      * @remarks
      * This method validates that:
-     * - The chain is a mainnet CCTPv2-supported chain (not testnet)
+     * - The chain is swap-supported (mainnet or whitelisted testnet with CCTPv2)
      * - Both tokens are supported (USDC, USDT, native currency, or token literals)
      * - The tokens are different (no same-token swaps)
      *
@@ -21249,10 +21095,7 @@ class StablecoinServiceSwapProvider {
      * ```
      */
     supportsRoute(tokenInAddress, tokenOutAddress, chain) {
-        if (chain.isTestnet) {
-            return false;
-        }
-        if (!isCCTPV2Supported(chain)) {
+        if (!isSwapSupportedChain(chain)) {
             return false;
         }
         // Normalize for same-token check
@@ -21854,7 +21697,22 @@ class StablecoinServiceSwapProvider {
         const swapResultFees = serviceResponse.fees
             ? await this.buildFormattedFees(serviceResponse.fees, chain, adapter, config?.customFee?.recipientAddress)
             : undefined;
-        const amountOut = await fetchLifiAmountOut(txHash, chain);
+        // Best-effort enrichment: fetch amountOut via the proxy service.
+        // If the call fails or times out, amountOut is simply omitted.
+        let amountOut;
+        try {
+            const statusResult = await getSwapStatus({
+                txHash,
+                chain: chain.chain,
+                apiKey: serviceParams.apiKey,
+            });
+            if (statusResult.status === 'DONE' && statusResult.amountOut) {
+                amountOut = statusResult.amountOut;
+            }
+        }
+        catch {
+            // Non-fatal — the swap already succeeded on-chain.
+        }
         // Build and return SwapResult
         return {
             tokenIn,
@@ -21982,85 +21840,355 @@ class StablecoinServiceSwapProvider {
 }
 
 /**
- * The default providers that will be used in addition to the providers provided
- * to the createSwapKitContext factory function.
+ * Schema for validating AdapterContext.
+ * Must always contain both adapter and chain explicitly.
+ * Optionally includes address for developer-controlled adapters.
+ */
+const adapterContextSchema$1 = z.object({
+    adapter: adapterSchema$1,
+    chain: swapChainIdentifierSchema,
+    address: z.string().optional(),
+});
+/**
+ * Schema for validating allowance strategy values.
+ */
+const allowanceStrategySchema = z.enum(['permit', 'approve']);
+/**
+ * Schema for validating SwapKit custom fee configuration.
  *
- * @returns An array containing the default StablecoinServiceSwapProvider
- * @internal
+ * Supports two mutually exclusive approaches:
+ * - Percentage-based: percentageBps + recipientAddress
+ * - Callback-based: amount + recipientAddress
+ *
+ * @remarks
+ * Mutual exclusivity is validated at runtime in buildServiceParams.
+ * Chain-specific address validation is performed in resolveSwapConfig.
  */
-const getDefaultProviders = () => [new StablecoinServiceSwapProvider()];
+const swapCustomFeeSchema = z
+    .object({
+    /**
+     * Fee percentage in basis points (percentage approach).
+     * 100 bps = 1%, must be > 0 and <= 10000.
+     */
+    percentageBps: z.number().int().positive().max(10000),
+    /**
+     * Fee recipient address (required).
+     * Must be a valid EVM address or Solana address.
+     */
+    recipientAddress: z
+        .string()
+        .refine((value) => evmAddressSchema.safeParse(value).success ||
+        solanaAddressSchema.safeParse(value).success, {
+        message: 'recipientAddress must be a valid blockchain address: EVM (0x + 40 hex chars) or Solana (base58, 32-44 chars)',
+    }),
+})
+    .strict();
 /**
- * Create a SwapKit context with validated configuration.
+ * Schema for validating swap configuration options.
  *
- * This factory function initializes a SwapKitContext with default providers
- * and optional custom configuration. It validates any provided custom fee
- * policy and merges default and custom providers, preserving their exact
- * types for type safety.
+ * Validates:
+ * - allowanceStrategy: Either 'permit' or 'approve'
+ * - slippageBps: Optional positive number for slippage tolerance
+ * - stopLimit: Optional decimal string for minimum output
+ * - customFee: Optional fee configuration
+ * - kitKey: Optional string identifier
+ */
+const swapConfigSchema = z.object({
+    allowanceStrategy: allowanceStrategySchema.optional(),
+    slippageBps: z.number().int().min(0).optional(),
+    stopLimit: z
+        .string()
+        .min(1, 'Required')
+        .pipe(createDecimalStringValidator({
+        allowZero: true,
+        regexMessage: 'Stop limit must be a numeric string with dot (.) as decimal separator (e.g., "0.1", ".1", "10.5", "1000.50"), with no thousand separators or comma decimals.',
+        attributeName: 'stopLimit',
+    })(z.string()))
+        .optional(),
+    customFee: swapCustomFeeSchema.optional(),
+    kitKey: z.string().optional(),
+});
+const EVM_ADDRESS_REGEX = /^0x[a-fA-F0-9]{40}$/;
+const SOLANA_ADDRESS_REGEX = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+const BASE58_CHARS_REGEX = /^[1-9A-HJ-NP-Za-km-z]+$/;
+/**
+ * Broad heuristic: return true when the input is composed entirely of
+ * base58 characters and is at least 32 characters long (the minimum
+ * length of a valid Solana address).
  *
- * The function is pure and side-effect-free, returning a plain context object
- * that can be used with swap operations. Default providers are currently
- * stubbed and will be implemented in future phases.
+ * The caller is expected to have already excluded valid Solana
+ * addresses (via {@link SOLANA_ADDRESS_REGEX}) before invoking this
+ * helper, so in practice it only matches over-length base58 strings
+ * (45+ chars) that are plausibly a malformed Solana address.
+ */
+function looksLikeSolanaAddress(value) {
+    return BASE58_CHARS_REGEX.test(value) && value.length >= 32;
+}
+const MAX_DISPLAY_LENGTH = 30;
+/** Truncate a value for safe inclusion in error messages. */
+function truncate(value) {
+    return value.length > MAX_DISPLAY_LENGTH
+        ? `${value.slice(0, MAX_DISPLAY_LENGTH)}...`
+        : value;
+}
+/**
+ * Schema for validating swap token input.
  *
- * @typeParam TExtraProviders - Array type of additional swap providers
- * @param config - Optional configuration for the SwapKit context
- * @returns A fully initialized SwapKitContext ready for swap operations
- * @throws \{ValidationError\} If the custom fee policy is invalid
+ * Accepts either:
+ * - Token symbols from the supported swap token registry ('USDC', 'WETH', 'NATIVE', etc.)
+ * - Token addresses (EVM: 0x..., Solana: base58)
+ *
+ * This allows swapping both supported tokens (by symbol or address) and
+ * arbitrary tokens (by address only), as long as at least one token is
+ * an "OK token" for fee collection purposes.
+ *
+ * @remarks
+ * Uses input-shape heuristics to produce contextual error messages:
+ * - Starts with `0x` — validated as EVM address
+ * - Recognized symbol — accepted
+ * - 32–44 base58 characters — accepted as Solana address
+ * - Otherwise — reports the most likely error (unsupported symbol,
+ *   malformed Solana address, or malformed EVM address)
+ *
+ * Runtime validation in `isOkToken` determines if the token is supported
+ * for fee collection. This schema only validates the format.
+ */
+let _symbolResult;
+const swapTokenSchema = z
+    .string()
+    .superRefine((value, ctx) => {
+    if (value.startsWith('0x')) {
+        if (!EVM_ADDRESS_REGEX.test(value)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Invalid EVM token address format. Expected '0x' followed by 40 hexadecimal characters, but received: '${truncate(value)}'`,
+            });
+        }
+        return;
+    }
+    _symbolResult = supportedSwapTokenSchema.safeParse(value);
+    if (_symbolResult.success) {
+        return;
+    }
+    if (SOLANA_ADDRESS_REGEX.test(value)) {
+        return;
+    }
+    if (looksLikeSolanaAddress(value)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Invalid Solana token address format. Expected 32-44 base58 characters, but received: '${truncate(value)}'`,
+        });
+        return;
+    }
+    ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Unknown token symbol '${truncate(value)}'. Supported symbols include USDC, USDT, WETH, NATIVE, and others. See SDK documentation for the full list. You can also provide a token contract address (EVM: 0x... or Solana: base58).`,
+    });
+})
+    .transform((value) => (_symbolResult?.success ? _symbolResult.data : value));
+// Amount-in validation schema - broken out to reduce type complexity
+const amountInSchema = z
+    .string()
+    .min(1, 'Required')
+    .pipe(createDecimalStringValidator({
+    allowZero: false,
+    regexMessage: AMOUNT_FORMAT_ERROR_MESSAGE,
+    attributeName: 'amountIn',
+    maxDecimals: 18,
+})(z.string()))
+    .describe('The amount of the input token to swap, expressed as a human-readable ' +
+    "decimal string in token units (e.g., '0.05' for 0.05 USDC or 0.05 ETH).");
+/**
+ * Schema for validating swap parameters with chain identifiers.
+ *
+ * This schema validates the complete swap operation input, ensuring:
+ * - Valid adapter context (adapter + chain + optional address)
+ * - Valid tokenIn and tokenOut (symbols or addresses)
+ * - Valid amountIn as a positive decimal string
+ * - Optional valid configuration
+ *
+ * The schema validates amounts with up to 18 decimal places to support
+ * various token standards.
  *
  * @example
  * ```typescript
- * import { createSwapKitContext } from '@circle-fin/swap-kit'
+ * import { swapParamsSchema } from '@circle-fin/swap-kit'
+ *
+ * // Using token symbols (recommended for supported tokens)
+ * const paramsWithSymbols = {
+ *   from: {
+ *     adapter: sourceAdapter,
+ *     chain: 'Ethereum'
+ *   },
+ *   tokenIn: 'USDC',
+ *   tokenOut: 'USDT',
+ *   amountIn: '100.50', // 100.50 USDC
+ *   config: {
+ *     slippageBps: 300,
+ *     allowanceStrategy: 'permit'
+ *   }
+ * }
+ *
+ * // Using token addresses (works for any token)
+ * const paramsWithAddresses = {
+ *   from: {
+ *     adapter: sourceAdapter,
+ *     chain: 'Base'
+ *   },
+ *   tokenIn: '0x4200000000000000000000000000000000000006', // WETH address
+ *   tokenOut: '0x532f27101965dd16442E59d40670FaF5eBB142E4', // Any token address
+ *   amountIn: '0.1' // 0.1 WETH
+ * }
+ *
+ * // Using native token alias
+ * const paramsWithNative = {
+ *   from: {
+ *     adapter: sourceAdapter,
+ *     chain: 'Ethereum'
+ *   },
+ *   tokenIn: 'NATIVE', // ETH on Ethereum, MATIC on Polygon, etc.
+ *   tokenOut: 'USDC',
+ *   amountIn: '1.5' // 1.5 ETH
+ * }
+ *
+ * const result = swapParamsSchema.safeParse(paramsWithSymbols)
+ * if (result.success) {
+ *   console.log('Parameters are valid')
+ * } else {
+ *   console.error('Validation failed:', result.error)
+ * }
+ * ```
+ */
+const swapParamsSchema = z.object({
+    from: adapterContextSchema$1,
+    tokenIn: swapTokenSchema,
+    tokenOut: swapTokenSchema,
+    amountIn: amountInSchema,
+    config: swapConfigSchema.optional(),
+});
+/**
+ * Schema for validating SwapKit custom fee policy.
+ *
+ * Validates the shape of CustomFeePolicy, which lets SDK consumers
+ * provide custom fee calculation and fee-recipient resolution logic.
+ *
+ * - computeFee: required function that returns a fee as a string (or Promise<string>).
+ * - resolveFeeRecipientAddress: required function that returns a recipient address as a
+ *   string (or Promise<string>).
+ *
+ * This schema only ensures the presence and return types of the functions; it
+ * does not validate their argument types.
+ *
+ * @example
+ * ```typescript
+ * import { customFeePolicySchema } from '@circle-fin/swap-kit'
+ *
+ * const config = {
+ *   computeFee: async () => '0.1',
+ *   resolveFeeRecipientAddress: () => '0x1234567890123456789012345678901234567890',
+ * }
+ *
+ * const result = customFeePolicySchema.safeParse(config)
+ * // result.success === true
+ * ```
+ */
+const customFeePolicySchema = z
+    .object({
+    computeFee: z.function().returns(z.string().or(z.promise(z.string()))),
+    resolveFeeRecipientAddress: z
+        .function()
+        .returns(z.string().or(z.promise(z.string()))),
+})
+    .strict();
+
+const assertCustomFeePolicySymbol = Symbol('assertCustomFeePolicy');
+/**
+ * Assert that the provided value conforms to {@link CustomFeePolicy}.
+ *
+ * This function validates the custom fee policy configuration using the
+ * customFeePolicySchema. It ensures that both required functions
+ * (computeFee and resolveFeeRecipientAddress) are present and have
+ * the correct return types.
+ *
+ * Throws a structured error with detailed validation messages if the
+ * configuration is malformed. Uses state tracking to avoid duplicate
+ * validations.
+ *
+ * @param config - The custom fee policy to validate
+ * @throws \{KitError\} If the policy fails validation
+ *
+ * @example
+ * ```typescript
+ * import { assertCustomFeePolicy } from '@circle-fin/swap-kit'
+ *
+ * const config = {
+ *   computeFee: () => '0.1',
+ *   resolveFeeRecipientAddress: () => '0x1234567890123456789012345678901234567890',
+ * }
+ *
+ * try {
+ *   assertCustomFeePolicy(config)
+ *   // If no error is thrown, `config` is a valid CustomFeePolicy
+ * } catch (error) {
+ *   console.error('Invalid fee policy:', error.message)
+ * }
+ * ```
+ */
+function assertCustomFeePolicy(config) {
+    // Use validateWithStateTracking to avoid duplicate validations
+    // This will skip validation if already validated by this function
+    // validateWithStateTracking now throws KitError directly with INPUT_VALIDATION_FAILED code
+    validateWithStateTracking(config, customFeePolicySchema, 'SwapKit custom fee policy', assertCustomFeePolicySymbol);
+}
+
+/**
+ * Symbol used to track that assertSwapParams has validated an object.
+ * @internal
+ */
+const ASSERT_SWAP_PARAMS_SYMBOL = Symbol('assertSwapParams');
+/**
+ * Assert that the provided value conforms to the SwapParams schema.
  *
- * // Create context with defaults
- * const context = createSwapKitContext()
- * ```
+ * This function validates swap parameters using the provided Zod schema
+ * and tracks validation state to avoid duplicate checks. It performs
+ * comprehensive validation including:
+ * - Adapter context structure
+ * - Token specifications
+ * - Amount format and range
+ * - Optional configuration values
  *
- * @example
- * ```typescript
- * import { createSwapKitContext } from '@circle-fin/swap-kit'
+ * Throws a structured error with detailed validation messages if
+ * any parameter is invalid.
  *
- * // Create context with custom fee policy
- * const context = createSwapKitContext({
- *   customFeePolicy: {
- *     computeFee: async (params) => {
- *       // Calculate based on swap amount
- *       return '0.1' // 0.1 USDC
- *     },
- *     resolveFeeRecipientAddress: async (chain, params) => {
- *       // Return recipient based on chain
- *       if (chain.type === 'solana') {
- *         return 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
- *       }
- *       return '0x1234567890123456789012345678901234567890'
- *     }
- *   }
- * })
- * ```
+ * @typeParam T - The expected type after validation
+ * @param params - The swap parameters to validate
+ * @param schema - The Zod schema to validate against
+ * @throws \{KitError\} If the parameters fail validation
  *
  * @example
  * ```typescript
- * import { createSwapKitContext } from '@circle-fin/swap-kit'
+ * import { assertSwapParams, swapParamsSchema } from '@circle-fin/swap-kit'
  *
- * // Create context with custom providers (future use)
- * const context = createSwapKitContext({
- *   providers: [] // Custom swap providers will be supported in future phases
- * })
+ * const params = {
+ *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
+ *   tokenIn: 'USDC',
+ *   tokenOut: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
+ *   amountIn: '100.50'
+ * }
+ *
+ * try {
+ *   assertSwapParams(params, swapParamsSchema)
+ *   // Parameters are valid, proceed with swap
+ * } catch (error) {
+ *   console.error('Invalid parameters:', error.message)
+ * }
  * ```
  */
-function createSwapKitContext(config = {}) {
-    // Validate custom fee policy if provided
-    if (config.customFeePolicy !== undefined) {
-        assertCustomFeePolicy(config.customFeePolicy);
-    }
-    // Initialize default providers
-    const defaultProviders = getDefaultProviders();
-    // Merge default and custom providers
-    const providers = [...defaultProviders, ...(config.providers ?? [])];
-    // Return the initialized context
-    return {
-        providers,
-        customFeePolicy: config.customFeePolicy ?? undefined,
-        tokens: createTokenRegistry(),
-    };
+function assertSwapParams(params, schema) {
+    // Use validateWithStateTracking to avoid duplicate validations
+    // This will skip validation if already validated by this function
+    // validateWithStateTracking now throws KitError directly with INPUT_VALIDATION_FAILED code
+    validateWithStateTracking(params, schema, 'swap parameters', ASSERT_SWAP_PARAMS_SYMBOL);
 }
 
 /**
@@ -23384,6 +23512,60 @@ class Amount {
     }
 }
 
+/**
+ * Return the stablecoin symbol that should replace NATIVE for chains whose
+ * native gas token is itself a supported stablecoin.
+ *
+ * @param chain - The chain definition to inspect.
+ * @returns `'USDC'` when the chain's native currency symbol is USDC and a
+ *   USDC contract address exists, `null` otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { ArcTestnet, Ethereum } from '@core/chains'
+ *
+ * getNativeStablecoinSymbol(ArcTestnet) // 'USDC'
+ * getNativeStablecoinSymbol(Ethereum)   // null
+ * ```
+ */
+function getNativeStablecoinSymbol(chain) {
+    if (chain.nativeCurrency.symbol.toUpperCase() === 'USDC' &&
+        chain.usdcAddress) {
+        return 'USDC';
+    }
+    return null;
+}
+/**
+ * Canonicalize the NATIVE alias to the matching stablecoin symbol on chains
+ * whose native gas token is itself a supported stablecoin.
+ *
+ * The comparison is case-insensitive for the NATIVE token identifier.
+ * Non-NATIVE inputs and native placeholder addresses (e.g. `0xEeee...`)
+ * pass through unchanged.
+ *
+ * @param token - The token symbol or alias to canonicalize.
+ * @param chain - The chain definition used for context-specific resolution.
+ * @returns The canonicalized token symbol. Returns `'USDC'` when `token` is
+ *   `'NATIVE'` on a native-stablecoin chain; otherwise returns `token`
+ *   unchanged.
+ *
+ * @example
+ * ```typescript
+ * import { ArcTestnet, Ethereum } from '@core/chains'
+ *
+ * canonicalizeNativeStablecoinAlias('NATIVE', ArcTestnet) // 'USDC'
+ * canonicalizeNativeStablecoinAlias('native', ArcTestnet) // 'USDC'
+ * canonicalizeNativeStablecoinAlias('NATIVE', Ethereum)   // 'NATIVE'
+ * canonicalizeNativeStablecoinAlias('USDC', ArcTestnet)   // 'USDC'
+ * ```
+ */
+function canonicalizeNativeStablecoinAlias(token, chain) {
+    if (token.toUpperCase() !== NATIVE_TOKEN) {
+        return token;
+    }
+    return getNativeStablecoinSymbol(chain) ?? token;
+}
+
 /**
  * Assert the resolved chain definition is supported by swap operations.
  *
@@ -23407,6 +23589,74 @@ function assertIsSwapSupportedChainDefinition(chain) {
         throw createValidationFailedError$1('chain', chain.chain, `Unsupported swap chain. Supported chains: ${supported}`);
     }
 }
+/**
+ * Resolve the on-chain address of the stablecoin that matches the
+ * native currency symbol, or `null` if there is no match.
+ */
+function getNativeStablecoinAddress(chain) {
+    if (getNativeStablecoinSymbol(chain) === 'USDC') {
+        return chain.usdcAddress;
+    }
+    return null;
+}
+/**
+ * Check whether a token input (symbol or address) refers to the
+ * native currency's underlying stablecoin on this chain.
+ */
+function isNativeEquivalent(token, nativeSymbol, nativeStablecoinAddress) {
+    const upper = token.toUpperCase();
+    if (upper === nativeSymbol)
+        return true;
+    if (upper === nativeStablecoinAddress.toUpperCase())
+        return true;
+    return false;
+}
+/**
+ * Check whether a token string represents the native gas token,
+ * either as the `"NATIVE"` alias or a well-known placeholder address.
+ */
+function isNativeTokenInput(token) {
+    const lower = token.toLowerCase();
+    if (lower === NATIVE_TOKEN.toLowerCase())
+        return true;
+    return OK_NATIVE_TOKEN_ADDRESSES_EVM.some((addr) => addr.toLowerCase() === lower);
+}
+/**
+ * Reject swaps between NATIVE and a token that IS the native currency.
+ *
+ * On chains like Arc where the native gas token is USDC, swapping
+ * USDC ↔ NATIVE is a no-op because they represent the same asset.
+ * This guard handles symbol inputs (`'USDC'`, `'NATIVE'`), raw
+ * contract addresses (`'0x3600...'`), and native placeholder
+ * addresses (`'0xEeee...'`, `'0x0000...'`).
+ *
+ * @param tokenIn - The input token alias or address
+ * @param tokenOut - The output token alias or address
+ * @param chain - The resolved chain definition
+ * @returns Nothing.
+ * @throws \{KitError\} When one side is NATIVE (alias or placeholder)
+ *   and the other matches the chain's native currency symbol or
+ *   contract address
+ */
+function assertNativeNotEquivalent(tokenIn, tokenOut, chain) {
+    const nativeStablecoinAddress = getNativeStablecoinAddress(chain);
+    if (nativeStablecoinAddress === null)
+        return;
+    const nativeSymbol = chain.nativeCurrency.symbol.toUpperCase();
+    const inIsNative = isNativeTokenInput(tokenIn);
+    const outIsNative = isNativeTokenInput(tokenOut);
+    const shouldReject = (inIsNative &&
+        isNativeEquivalent(tokenOut, nativeSymbol, nativeStablecoinAddress)) ||
+        (outIsNative &&
+            isNativeEquivalent(tokenIn, nativeSymbol, nativeStablecoinAddress)) ||
+        (inIsNative && outIsNative);
+    if (shouldReject) {
+        throw createValidationFailedError$1(inIsNative ? 'tokenIn' : 'tokenOut', inIsNative ? tokenIn : tokenOut, `On ${chain.name}, the native gas token is ${nativeSymbol}. ` +
+            `Swapping between NATIVE and ${nativeSymbol} is not supported ` +
+            `because they represent the same asset. ` +
+            `Use ${nativeSymbol} directly instead of NATIVE.`);
+    }
+}
 /**
  * Resolves the amount of a swap by formatting it according to the token's decimal places.
  *
@@ -23517,12 +23767,14 @@ async function resolveSwapConfig(params, chain, tokens, adapter) {
  * Resolves swap parameters from user input to provider-consumable format.
  *
  * Transforms SwapParams with chain identifiers and token aliases into
- * ResolvedSwapParams with full chain definitions, preserved token aliases,
+ * ResolvedSwapParams with full chain definitions, canonicalized token aliases,
  * and validated wallet addresses. Uses the TokenRegistry from context for
  * decimal resolution.
  *
- * Note: Token aliases ('USDC', 'USDT', 'NATIVE') are preserved and passed
- * through unchanged. Address resolution is handled by the provider layer.
+ * Note: Raw user input is validated first, then `NATIVE` may be canonicalized
+ * to a stablecoin symbol on chains whose native gas token is itself a
+ * supported stablecoin (for example, Arc Testnet `NATIVE` → `USDC`).
+ * Address resolution is handled by the provider layer.
  *
  * @typeParam TFromAdapterCapabilities - The adapter capabilities type for the source adapter
  * @param params - The input swap parameters to resolve
@@ -23550,8 +23802,8 @@ async function resolveSwapConfig(params, chain, tokens, adapter) {
  *   amountIn: '100.5'
  * }, tokens)
  *
- * // resolved.tokenIn === 'USDC'  // Alias preserved
- * // resolved.tokenOut === 'USDT' // Alias preserved
+ * // resolved.tokenIn === 'USDC'  // Canonicalized for provider routing
+ * // resolved.tokenOut === 'USDT' // Canonicalized for provider routing
  * // resolved.to === wallet address from adapter
  * ```
  */
@@ -23562,16 +23814,20 @@ async function resolveSwapParams(params, tokens) {
     const resolvedChain = resolveChainIdentifier(params.from.chain);
     assertIsSwapSupportedChainDefinition(resolvedChain);
     const fromChain = resolvedChain;
+    assertNativeNotEquivalent(params.tokenIn, params.tokenOut, fromChain);
     params.from.adapter.validateChainSupport(fromChain);
     // Cast required: SwapAdapterContext and AdapterContext differ in their
     // optional address field handling under exactOptionalPropertyTypes.
     const walletAddress = await resolveAddress(params.from);
-    // Pass token aliases directly to the resolved params
-    // Resolution to addresses will be handled by the provider
-    const tokenIn = params.tokenIn;
-    const tokenOut = params.tokenOut;
-    const resolvedAmount = await resolveAmount(params.amountIn, params.tokenIn, fromChain, tokens, params.from.adapter);
-    const resolvedConfig = await resolveSwapConfig(params, fromChain, tokens, params.from.adapter);
+    // Canonicalize NATIVE after raw-input validation so native-stablecoin
+    // chains use stablecoin decimals and downstream provider routing.
+    const tokenIn = canonicalizeNativeStablecoinAlias(params.tokenIn, fromChain);
+    const tokenOut = canonicalizeNativeStablecoinAlias(params.tokenOut, fromChain);
+    const resolvedAmount = await resolveAmount(params.amountIn, tokenIn, fromChain, tokens, params.from.adapter);
+    const resolvedConfig = await resolveSwapConfig({
+        ...params,
+        tokenOut,
+    }, fromChain, tokens, params.from.adapter);
     return {
         from: {
             ...params.from,
@@ -23836,6 +24092,10 @@ const formatConfig = (config, outputTokenTransform) => {
     if (Object.keys(cloneConfig).length === 0) {
         return undefined;
     }
+    // Transform stopLimit if present (minimum output amount, uses output token decimals)
+    if (cloneConfig.stopLimit !== undefined) {
+        cloneConfig.stopLimit = outputTokenTransform(cloneConfig.stopLimit);
+    }
     // Handle customFee transformation
     if (config.customFee !== undefined) {
         const { amount, percentageBps, recipientAddress } = config.customFee;
@@ -23950,7 +24210,9 @@ function getNativeTokenAddress(chain) {
  * The quote endpoint requires resolved addresses, not aliases. This function
  * mirrors the provider's `resolveTokenAlias` logic using the context's
  * TokenRegistry:
- * - "NATIVE" alias → chain-specific native token placeholder address
+ * - "NATIVE" alias → native token placeholder, unless the chain's native gas
+ *   token is a supported stablecoin, in which case it canonicalizes to the
+ *   stablecoin symbol and resolves through the registry
  * - Native currency symbol (ETH, SOL, MON, etc.) → native token placeholder
  * - Known symbols (USDC, USDT, etc.) → resolved chain-specific address
  * - Already-an-address strings → passed through unchanged
@@ -23963,9 +24225,13 @@ function getNativeTokenAddress(chain) {
  */
 function resolveTokenForQuote(token, chain, tokens) {
     const upperToken = token.toUpperCase();
-    // Handle NATIVE alias and native currency symbols (ETH, SOL, MON, etc.)
+    const nativeStablecoinSymbol = getNativeStablecoinSymbol(chain);
+    // Handle native aliases and native currency symbols for standard native-token
+    // chains. On native-stablecoin chains, canonicalized symbols should resolve
+    // via the token registry instead of the native placeholder.
     if (upperToken === 'NATIVE' ||
-        upperToken === chain.nativeCurrency.symbol.toUpperCase()) {
+        (nativeStablecoinSymbol === null &&
+            upperToken === chain.nativeCurrency.symbol.toUpperCase())) {
         return getNativeTokenAddress(chain);
     }
     // If the token is a known symbol in the registry, resolve to address
@@ -24027,8 +24293,15 @@ async function handleOutputFeeCallback(context, params) {
         // Resolve token aliases to addresses for the quote API
         // The quote endpoint requires resolved addresses, not aliases like 'USDC'
         const chain = params.from.chain;
-        const resolvedTokenIn = resolveTokenForQuote(params.tokenIn, chain, context.tokens);
-        const resolvedTokenOut = resolveTokenForQuote(params.tokenOut, chain, context.tokens);
+        const tokenIn = canonicalizeNativeStablecoinAlias(params.tokenIn, chain);
+        const tokenOut = canonicalizeNativeStablecoinAlias(params.tokenOut, chain);
+        const canonicalizedParams = {
+            ...params,
+            tokenIn,
+            tokenOut,
+        };
+        const resolvedTokenIn = resolveTokenForQuote(canonicalizedParams.tokenIn, chain, context.tokens);
+        const resolvedTokenOut = resolveTokenForQuote(canonicalizedParams.tokenOut, chain, context.tokens);
         const quoteParams = {
             tokenInAddress: resolvedTokenIn,
             tokenInChain: chain.chain, // Use enum value (e.g., "World_Chain")
@@ -24046,7 +24319,7 @@ async function handleOutputFeeCallback(context, params) {
         const quoteResponse = await getQuote(quoteParams);
         // Step 3: Build fee context from quote
         const feeContext = {
-            ...params,
+            ...canonicalizedParams,
             type: 'output',
             minAmount: quoteResponse.quote.minAmount,
             estimatedAmount: quoteResponse.quote.estimatedAmount,
@@ -24154,8 +24427,8 @@ async function estimate(context, params) {
     // Return the estimate with input context fields populated
     return {
         // Input context fields
-        tokenIn: params.tokenIn,
-        tokenOut: params.tokenOut,
+        tokenIn: resolvedParams.tokenIn,
+        tokenOut: resolvedParams.tokenOut,
         amountIn: params.amountIn,
         chain: chainName,
         fromAddress: resolvedParams.from.address,
@@ -24279,11 +24552,11 @@ async function swap$1(context, params) {
     };
     const providerResult = await provider.swap(swapParams);
     const [tokenInDecimals, tokenOutDecimals] = await Promise.all([
-        getTokenDecimals(params.tokenIn, resolvedParams.from.chain, resolvedParams.from.adapter, context.tokens),
-        getTokenDecimals(params.tokenOut, resolvedParams.from.chain, resolvedParams.from.adapter, context.tokens),
+        getTokenDecimals(resolvedParams.tokenIn, resolvedParams.from.chain, resolvedParams.from.adapter, context.tokens),
+        getTokenDecimals(resolvedParams.tokenOut, resolvedParams.from.chain, resolvedParams.from.adapter, context.tokens),
     ]);
     // Step 6: Format provider result to human-readable values
-    return formatSwapResult(providerResult, 'to-human-readable', params.tokenIn, params.tokenOut, tokenInDecimals, tokenOutDecimals);
+    return formatSwapResult(providerResult, 'to-human-readable', resolvedParams.tokenIn, resolvedParams.tokenOut, tokenInDecimals, tokenOutDecimals);
 }
 
 /**
@@ -24349,9 +24622,10 @@ function getSupportedChains$1(context) {
  * This function follows an immutable pattern, returning a new context with the
  * wrapped policy attached. The original context remains unchanged.
  *
+ * @typeParam TProviders - The tuple of swap providers in the context, preserved through the returned context
  * @param context - The SwapKitContext to configure with the custom fee policy
  * @param customFeePolicy - The custom fee policy containing fee calculation and recipient resolution logic
- * @returns A new SwapKitContext with the custom fee policy configured
+ * @returns A new SwapKitContext\<TProviders\> with the custom fee policy configured, preserving the original provider types
  * @throws \{ValidationError\} If the custom fee policy is invalid or missing required functions
  * @throws \{KitError\} If the token is not supported (not USDC, USDT, or NATIVE)
  *
@@ -24497,6 +24771,90 @@ function removeCustomFeePolicy(context) {
     };
 }
 
+/**
+ * The default providers that will be used in addition to the providers provided
+ * to the createSwapKitContext factory function.
+ *
+ * @returns An array containing the default StablecoinServiceSwapProvider
+ * @internal
+ */
+const getDefaultProviders = () => [new StablecoinServiceSwapProvider()];
+/**
+ * Create a SwapKit context with validated configuration.
+ *
+ * This factory function initializes a SwapKitContext with default providers
+ * and optional custom configuration. It validates any provided custom fee
+ * policy and merges default and custom providers, preserving their exact
+ * types for type safety.
+ *
+ * The function is pure and side-effect-free, returning a plain context object
+ * that can be used with swap operations. Default providers are currently
+ * stubbed and will be implemented in future phases.
+ *
+ * @typeParam TExtraProviders - Array type of additional swap providers
+ * @param config - Optional configuration for the SwapKit context
+ * @returns A fully initialized SwapKitContext ready for swap operations
+ * @throws \{ValidationError\} If the custom fee policy is invalid
+ *
+ * @example
+ * ```typescript
+ * import { createSwapKitContext } from '@circle-fin/swap-kit'
+ *
+ * // Create context with defaults
+ * const context = createSwapKitContext()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createSwapKitContext } from '@circle-fin/swap-kit'
+ *
+ * // Create context with custom fee policy
+ * const context = createSwapKitContext({
+ *   customFeePolicy: {
+ *     computeFee: async (params) => {
+ *       // Calculate based on swap amount
+ *       return '0.1' // 0.1 USDC
+ *     },
+ *     resolveFeeRecipientAddress: async (chain, params) => {
+ *       // Return recipient based on chain
+ *       if (chain.type === 'solana') {
+ *         return 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
+ *       }
+ *       return '0x1234567890123456789012345678901234567890'
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createSwapKitContext } from '@circle-fin/swap-kit'
+ *
+ * // Create context with custom providers (future use)
+ * const context = createSwapKitContext({
+ *   providers: [] // Custom swap providers will be supported in future phases
+ * })
+ * ```
+ */
+function createSwapKitContext(config = {}) {
+    // Initialize default providers
+    const defaultProviders = getDefaultProviders();
+    // Merge default and custom providers
+    const providers = [...defaultProviders, ...(config.providers ?? [])];
+    // Build base context without fee policy
+    const context = {
+        providers,
+        customFeePolicy: undefined,
+        tokens: createTokenRegistry(),
+    };
+    // If fee policy provided, apply wrapping via setCustomFeePolicy
+    // This ensures computeFee converts between human-readable and base units
+    if (config.customFeePolicy !== undefined) {
+        return setCustomFeePolicy(context, config.customFeePolicy);
+    }
+    return context;
+}
+
 /**
  * A high-level class-based interface for single-chain token swap operations.
  *
@@ -25635,6 +25993,56 @@ const bridge = async (context, params) => {
     return kit.bridge(params);
 };
 
+/**
+ * Retry a failed cross-chain bridge operation using the AppKit context.
+ *
+ * This function provides a standardized interface for retrying bridge
+ * operations within the AppKit ecosystem. It delegates to the underlying
+ * BridgeKit retry infrastructure while maintaining consistency with the
+ * AppKit patterns and context-based architecture.
+ *
+ * Use this after detecting a retryable error on a failed step via
+ * {@link isRetryableError} to resume a bridge that failed due to a
+ * transient issue.
+ *
+ * @param context - The AppKit context containing action handlers
+ * @param result - The bridge result from the failed operation
+ * @param retryContext - The retry context with source and optional
+ *   destination adapters
+ * @returns Promise resolving to the bridge result with transaction
+ *   details
+ * @throws If the provider from the original result is not found
+ * @throws If the retry operation fails
+ *
+ * @example
+ * ```typescript
+ * import { AppKit, isRetryableError } from '@circle-fin/app-kit'
+ *
+ * const kit = new AppKit()
+ *
+ * const result = await kit.bridge({
+ *   from: sourceAdapter,
+ *   to: { adapter: destAdapter, chain: 'Polygon' },
+ *   amount: '100.50',
+ * })
+ *
+ * const failedStep = result.steps.find(s => s.error)
+ * if (result.state === 'error' && failedStep?.error && isRetryableError(failedStep.error)) {
+ *   const retried = await kit.retryBridge(result, {
+ *     from: sourceAdapter,
+ *     to: destAdapter,
+ *   })
+ *   console.log('Retry result:', retried.state)
+ * }
+ * ```
+ */
+const retryBridge = async (context, result, retryContext) => {
+    const kit = createBridgeKit(context);
+    registerActionHandlers(kit, context.actions.bridge, 'bridge');
+    // Delegate to the BridgeKit for actual retry execution
+    return kit.retry(result, retryContext);
+};
+
 /**
  * Execute a same-chain token swap operation using the AppKit context.
  *
@@ -25906,6 +26314,46 @@ class AppKit {
     async bridge(params) {
         return bridge(this.context, params);
     }
+    /**
+     * Retry a failed cross-chain USDC bridge transfer.
+     *
+     * Resume a bridge operation that failed due to a transient error.
+     * Use {@link isRetryableError} to check whether a failed step's error
+     * is eligible for retry before calling this method.
+     *
+     * @param result - The bridge result from the failed operation
+     * @param retryContext - The retry context with source and optional
+     *   destination adapters
+     * @returns Promise resolving to the bridge result with transaction
+     *   details
+     * @throws If the provider from the original result is not found
+     * @throws If the retry operation fails
+     *
+     * @example
+     * ```typescript
+     * import { AppKit, isRetryableError } from '@circle-fin/app-kit'
+     *
+     * const kit = new AppKit()
+     *
+     * const result = await kit.bridge({
+     *   from: sourceAdapter,
+     *   to: { adapter: destAdapter, chain: 'Polygon' },
+     *   amount: '100.50',
+     * })
+     *
+     * const failedStep = result.steps.find(s => s.error)
+     * if (result.state === 'error' && failedStep?.error && isRetryableError(failedStep.error)) {
+     *   const retried = await kit.retryBridge(result, {
+     *     from: sourceAdapter,
+     *     to: destAdapter,
+     *   })
+     *   console.log('Retry result:', retried.state)
+     * }
+     * ```
+     */
+    async retryBridge(result, retryContext) {
+        return retryBridge(this.context, result, retryContext);
+    }
     /**
      * Estimate the bridge operation.
      *