@circle-fin/app-kit 1.11.0 → 1.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circle-fin/app-kit",
-  "version": "1.11.0",
+  "version": "1.12.1",
   "description": "A one-stop Circle SDK solution for building stablecoin (e.g. USDC) applications, with bridging, swapping, and more on-chain operations",
   "keywords": [
     "circle",
@@ -36,11 +36,11 @@
   "module": "./index.mjs",
   "types": "./index.d.cts",
   "dependencies": {
-    "@circle-fin/unified-balance-kit": "1.3.1",
-    "@circle-fin/provider-gateway-v1": "1.1.4",
-    "@circle-fin/earn-kit": "1.4.0",
-    "@circle-fin/bridge-kit": "1.12.2",
-    "@circle-fin/swap-kit": "1.5.0",
+    "@circle-fin/unified-balance-kit": "1.4.1",
+    "@circle-fin/provider-gateway-v1": "1.2.1",
+    "@circle-fin/earn-kit": "1.5.1",
+    "@circle-fin/bridge-kit": "1.13.0",
+    "@circle-fin/swap-kit": "1.5.2",
     "@coral-xyz/anchor": "^0.31.1",
     "@noble/curves": "1.4.2",
     "bn.js": "^5.2.3",

package/swap.cjs

@@ -40,6 +40,7 @@ require('@coral-xyz/anchor');
 var bs58 = require('bs58');
 require('@noble/curves/ed25519');
 var units = require('@ethersproject/units');
+require('viem');
 var keccak256 = require('@ethersproject/keccak256');
 
 function _interopDefault (e) { return e && e.__esModule ? e.default : e; }
@@ -3008,6 +3009,8 @@ class KitError extends Error {
     Blockchain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
     Blockchain["XDC"] = "XDC";
     Blockchain["XDC_Apothem"] = "XDC_Apothem";
+    Blockchain["X_Layer"] = "X_Layer";
+    Blockchain["X_Layer_Testnet"] = "X_Layer_Testnet";
     Blockchain["ZKSync_Era"] = "ZKSync_Era";
     Blockchain["ZKSync_Sepolia"] = "ZKSync_Sepolia";
 })(Blockchain || (Blockchain = {}));
@@ -3061,6 +3064,7 @@ var BridgeChain;
     BridgeChain["Unichain"] = "Unichain";
     BridgeChain["World_Chain"] = "World_Chain";
     BridgeChain["XDC"] = "XDC";
+    BridgeChain["X_Layer"] = "X_Layer";
     // Testnet chains with CCTPv2 support
     BridgeChain["Arc_Testnet"] = "Arc_Testnet";
     BridgeChain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
@@ -3086,6 +3090,7 @@ var BridgeChain;
     BridgeChain["Unichain_Sepolia"] = "Unichain_Sepolia";
     BridgeChain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
     BridgeChain["XDC_Apothem"] = "XDC_Apothem";
+    BridgeChain["X_Layer_Testnet"] = "X_Layer_Testnet";
 })(BridgeChain || (BridgeChain = {}));
 var UnifiedBalanceChain;
 (function(UnifiedBalanceChain) {
@@ -5634,7 +5639,8 @@ var EarnChain;
     isTestnet: true,
     explorerUrl: 'https://amoy.polygonscan.com/tx/{hash}',
     rpcEndpoints: [
-        'https://rpc-amoy.polygon.technology'
+        'https://polygon-amoy-bor-rpc.publicnode.com',
+        'https://polygon-amoy.drpc.org'
     ],
     eurcAddress: null,
     usdcAddress: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
@@ -6499,6 +6505,104 @@ var EarnChain;
     }
 });
 
+/**
+ * X Layer Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the X Layer blockchain.
+ * X Layer is an EVM-compatible OP Stack Layer-2 blockchain built by OKX,
+ * using OKB as its native gas token. (Migrated from Polygon zkEVM/CDK to the
+ * OP Stack on 2025-10-27; older docs describing it as zkEVM are obsolete.)
+ */ const XLayer = defineChain({
+    type: 'evm',
+    chain: Blockchain.X_Layer,
+    name: 'X Layer',
+    title: 'X Layer Mainnet',
+    nativeCurrency: {
+        name: 'OKB',
+        symbol: 'OKB',
+        decimals: 18
+    },
+    chainId: 196,
+    isTestnet: false,
+    explorerUrl: 'https://www.oklink.com/xlayer/tx/{hash}',
+    rpcEndpoints: [
+        'https://xlayerrpc.okx.com'
+    ],
+    eurcAddress: null,
+    usdcAddress: '0xB6CEceAB302E2E4948951eE7843FC24E92933061',
+    usdtAddress: null,
+    cctp: {
+        domain: 37,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 65,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET
+    }
+});
+
+/**
+ * X Layer Testnet chain definition
+ * @remarks
+ * This represents the official test network for the X Layer blockchain.
+ * X Layer is an EVM-compatible OP Stack Layer-2 blockchain built by OKX,
+ * using OKB as its native gas token. (Migrated from Polygon zkEVM/CDK to the
+ * OP Stack on 2025-10-27; older docs describing it as zkEVM are obsolete.)
+ */ const XLayerTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.X_Layer_Testnet,
+    name: 'X Layer Testnet',
+    title: 'X Layer Testnet',
+    nativeCurrency: {
+        name: 'OKB',
+        symbol: 'OKB',
+        decimals: 18
+    },
+    chainId: 1952,
+    isTestnet: true,
+    // Deliberately not oklink.com (used for mainnet): viem's bundled OKLink
+    // testnet URL targets the deprecated pre-rebrand chain ID 195, not this
+    // chain's ID (1952). Verified against the internal chain-expansion-scripts
+    // config (`v2config.sandbox.yml`) — do not "normalize" this to match mainnet.
+    explorerUrl: 'https://web3.okx.com/explorer/x-layer-testnet/tx/{hash}',
+    rpcEndpoints: [
+        'https://testrpc.xlayer.tech'
+    ],
+    eurcAddress: null,
+    usdcAddress: '0xDec90b78111Ba2fc6FC6d84d8B9ec159A2d4b9B3',
+    usdtAddress: null,
+    cctp: {
+        domain: 37,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 65,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET
+    }
+});
+
 /**
  * ZKSync Era Mainnet chain definition
  * @remarks
@@ -6618,6 +6722,8 @@ var Chains = {
   WorldChainSepolia: WorldChainSepolia,
   XDC: XDC,
   XDCApothem: XDCApothem,
+  XLayer: XLayer,
+  XLayerTestnet: XLayerTestnet,
   ZKSyncEra: ZKSyncEra,
   ZKSyncEraSepolia: ZKSyncEraSepolia
 };
@@ -8646,6 +8752,7 @@ const swapTokenEnumSchema = zod.z.enum([
         [Blockchain.Unichain]: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
         [Blockchain.World_Chain]: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
         [Blockchain.XDC]: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
+        [Blockchain.X_Layer]: '0xB6CEceAB302E2E4948951eE7843FC24E92933061',
         [Blockchain.ZKSync_Era]: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
         // =========================================================================
         // Testnets (alphabetically sorted)
@@ -8654,6 +8761,7 @@ const swapTokenEnumSchema = zod.z.enum([
         [Blockchain.Arbitrum_Sepolia]: '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
         [Blockchain.Avalanche_Fuji]: '0x5425890298aed601595a70AB815c96711a31Bc65',
         [Blockchain.Base_Sepolia]: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+        [Blockchain.Celo_Alfajores_Testnet]: '0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B',
         [Blockchain.Codex_Testnet]: '0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f',
         [Blockchain.Cronos_Testnet]: '0xEb33dc5fac03833e132593659e1dE7256aB59794',
         [Blockchain.Edge_Testnet]: '0x2d9F7CAD728051AA35Ecdc472a14cf8cDF5CFD6B',
@@ -8680,6 +8788,7 @@ const swapTokenEnumSchema = zod.z.enum([
         [Blockchain.Unichain_Sepolia]: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
         [Blockchain.World_Chain_Sepolia]: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
         [Blockchain.XDC_Apothem]: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
+        [Blockchain.X_Layer_Testnet]: '0xDec90b78111Ba2fc6FC6d84d8B9ec159A2d4b9B3',
         [Blockchain.ZKSync_Sepolia]: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853'
     }
 };
@@ -9967,7 +10076,7 @@ const swapTokenEnumSchema = zod.z.enum([
 }
 
 var name$2 = "@circle-fin/bridge-kit";
-var version$2 = "1.12.2";
+var version$2 = "1.13.0";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -10003,15 +10112,61 @@ var pkg$2 = {
     computeFee: zod.z.function().returns(zod.z.string().or(zod.z.promise(zod.z.string()))).optional(),
     calculateFee: zod.z.function().returns(zod.z.string().or(zod.z.promise(zod.z.string()))).optional(),
     resolveFeeRecipientAddress: zod.z.function().returns(zod.z.string().or(zod.z.promise(zod.z.string())))
-}).strict().refine((data)=>{
+}).strict().superRefine((data, ctx)=>{
     const hasComputeFee = data.computeFee !== undefined;
     const hasCalculateFee = data.calculateFee !== undefined;
-    // XOR: exactly one must be provided
-    return hasComputeFee !== hasCalculateFee;
-}, {
-    message: 'Provide either computeFee or calculateFee, not both. Use computeFee (recommended) for human-readable amounts.'
+    if (hasComputeFee && hasCalculateFee) {
+        ctx.addIssue({
+            code: zod.z.ZodIssueCode.custom,
+            message: 'Provide either computeFee or calculateFee, not both. Use computeFee (recommended) for human-readable amounts.'
+        });
+    }
+    if (!hasComputeFee && !hasCalculateFee) {
+        ctx.addIssue({
+            code: zod.z.ZodIssueCode.custom,
+            message: 'Provide either computeFee or calculateFee. Use computeFee (recommended) for human-readable amounts.'
+        });
+    }
 });
 
+/**
+ * Canonical list of actions that do not prepare or submit transactions.
+ *
+ * @internal
+ */ const READ_ACTION_KEYS = [
+    'token.allowance',
+    'token.balanceOf',
+    'token.name',
+    'native.balanceOf',
+    'usdc.allowance',
+    'usdc.balanceOf',
+    'usdc.name',
+    'gateway.v1.isDelegate',
+    'gateway.v1.withdrawingBalance',
+    'gateway.v1.withdrawalBlock',
+    'gateway.v1.signBurnIntents'
+];
+const READ_ACTION_KEY_SET = new Set(READ_ACTION_KEYS);
+/**
+ * Check whether a runtime value identifies a read action.
+ *
+ * @param action - The value to classify.
+ * @returns Whether the value is a registered read-action key.
+ *
+ * @example
+ * ```typescript
+ * import { isReadActionKey } from '@core/adapter'
+ *
+ * if (isReadActionKey(value)) {
+ *   await adapter.readAction(value, params, context)
+ * }
+ * ```
+ *
+ * @internal
+ */ function isReadActionKey(action) {
+    return typeof action === 'string' && READ_ACTION_KEY_SET.has(action);
+}
+
 /**
  * Resolves an operation context into concrete chain and address values.
  *
@@ -10091,6 +10246,141 @@ var pkg$2 = {
     };
 }
 
+/**
+ * Create the standard error for a missing or non-read action.
+ *
+ * @param action - The unsupported action value.
+ * @returns A fatal unsupported-action error.
+ *
+ * @internal
+ */ function createUnsupportedReadActionError(action) {
+    return new KitError({
+        ...InputError.UNSUPPORTED_ACTION,
+        recoverability: 'FATAL',
+        message: `Read action "${String(action)}" is not registered in this adapter.`
+    });
+}
+/**
+ * Execute a read through the adapter's dedicated read seam when available.
+ *
+ * @remarks
+ * Fall back to the legacy `prepareAction().execute()` contract so providers
+ * remain runtime-compatible with adapter versions released before `readAction`.
+ * Consumers must upgrade their adapter package for reads to bypass custom
+ * `prepareAction` wrappers.
+ *
+ * @typeParam TAdapterCapabilities - The adapter capabilities type.
+ * @typeParam TActionKey - The read action key.
+ * @param adapter - The adapter that owns the read action.
+ * @param action - The read action to execute.
+ * @param params - The parameters for the read action.
+ * @param ctx - The operation context.
+ * @returns The raw read-action result.
+ * @throws {KitError} When `action` is not a supported read-action key.
+ *
+ * @example
+ * ```typescript
+ * import { executeAdapterReadAction } from '@core/adapter'
+ * import { Ethereum } from '@core/chains'
+ *
+ * const allowance = await executeAdapterReadAction(
+ *   adapter,
+ *   'token.allowance',
+ *   { tokenAddress, delegate },
+ *   { chain: Ethereum },
+ * )
+ * ```
+ *
+ * @internal
+ */ async function executeAdapterReadAction(adapter, action, params, ctx) {
+    if (!isReadActionKey(action)) {
+        throw createUnsupportedReadActionError(action);
+    }
+    const runtimeAdapter = adapter;
+    if (typeof runtimeAdapter.readAction === 'function') {
+        return runtimeAdapter.readAction(action, params, ctx);
+    }
+    let request;
+    try {
+        request = await adapter.prepareAction(action, params, ctx);
+    } catch (error) {
+        if (error instanceof Error && error.message === `Action ${action} is not supported`) {
+            throw createUnsupportedReadActionError(action);
+        }
+        throw error;
+    }
+    return request.execute();
+}
+/**
+ * Read and parse a token allowance while supporting older adapter versions.
+ *
+ * @remarks
+ * Prefer the adapter's dedicated read seam and fall back to the legacy
+ * `prepareAction().execute()` contract when the runtime adapter predates it.
+ *
+ * @typeParam TAdapterCapabilities - The adapter capabilities type.
+ * @param adapter - The adapter that owns the allowance action.
+ * @param params - The token and delegate whose allowance is being read.
+ * @param ctx - The operation context.
+ * @returns The non-negative allowance in token base units.
+ * @throws {KitError} When the action is unsupported or its response is malformed.
+ *
+ * @example
+ * ```typescript
+ * import { readTokenAllowance } from '@core/adapter'
+ * import { Ethereum } from '@core/chains'
+ *
+ * const allowance = await readTokenAllowance(
+ *   adapter,
+ *   { tokenAddress, delegate },
+ *   { chain: Ethereum },
+ * )
+ * ```
+ *
+ * @internal
+ */ async function readTokenAllowance(adapter, params, ctx) {
+    return parseAllowanceResponse(await executeAdapterReadAction(adapter, 'token.allowance', params, ctx));
+}
+/**
+ * Parse a raw token allowance response into base units.
+ *
+ * @param allowanceRaw - The adapter response, optionally wrapped as an Amount output.
+ * @returns The non-negative allowance as a bigint, or zero for a missing value.
+ * @throws {KitError} When the response cannot represent a non-negative bigint.
+ *
+ * @example
+ * ```typescript
+ * import { parseAllowanceResponse } from '@core/adapter'
+ *
+ * const allowance = parseAllowanceResponse({ amount: { raw: 1000000n } })
+ * ```
+ */ function parseAllowanceResponse(allowanceRaw) {
+    let value = allowanceRaw;
+    if (typeof value === 'object' && value !== null && 'amount' in value) {
+        const amount = value.amount;
+        if (typeof amount === 'object' && amount !== null && 'raw' in amount) {
+            value = amount.raw;
+        }
+    }
+    if (value === undefined || value === null) {
+        return 0n;
+    }
+    let allowance;
+    if (typeof value === 'bigint') {
+        allowance = value;
+    } else if (typeof value === 'string') {
+        try {
+            allowance = BigInt(value);
+        } catch  {
+            allowance = undefined;
+        }
+    }
+    if (allowance === undefined || allowance < 0n) {
+        throw createValidationFailedError$1('token.allowance', value, 'token.allowance response must be a non-negative bigint-compatible string or bigint');
+    }
+    return allowance;
+}
+
 /**
  * Schema for validating hexadecimal strings with '0x' prefix.
  *
@@ -10868,7 +11158,7 @@ var TransferSpeed;
 registerKit(`${pkg$2.name}/${pkg$2.version}`);
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.5.0";
+var version$1 = "1.5.2";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -15188,14 +15478,13 @@ const TOKEN_REGISTRY$2 = createTokenRegistry();
         return;
     }
     // For non-native tokens (SPL tokens, ERC-20 tokens), check the token balance
-    const balancePrepared = await adapter.prepareAction('token.balanceOf', {
+    const balance = await executeAdapterReadAction(adapter, 'token.balanceOf', {
         tokenAddress: tokenInAddress,
         walletAddress
     }, context);
-    const balance = await balancePrepared.execute();
     // Compare balances
     const requiredAmount = BigInt(amount);
-    const currentBalance = BigInt(balance);
+    const currentBalance = BigInt(String(balance));
     if (currentBalance < requiredAmount) {
         throw new KitError({
             ...BalanceError.INSUFFICIENT_TOKEN,
@@ -16356,11 +16645,10 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
    * @throws Error if the adapter fails to prepare or execute approval transactions
    * @throws Error if transaction confirmation fails or times out
    */ async handleUsdtApproval(adapter, chain, executionCtx, adapterContractAddress, resolvedContext, executedTransactions) {
-        const allowanceRequest = await adapter.prepareAction('token.allowance', {
+        const current = await readTokenAllowance(adapter, {
             tokenAddress: executionCtx.tokenInAddress,
             delegate: adapterContractAddress
         }, resolvedContext);
-        const current = BigInt(await allowanceRequest.execute());
         const required = BigInt(executionCtx.amount);
         if (current >= required) {
             // Sufficient allowance - proceed to swap
@@ -21073,7 +21361,9 @@ registerKit(`${pkg$1.name}/${pkg$1.version}`);
             disableAnalytics: context.disableAnalytics
         }
     });
-    if (hasBoth) {
+    if (context.customFeePolicy?.swap != null) {
+        kit.setCustomFeePolicy(context.customFeePolicy.swap);
+    } else if (hasBoth) {
         kit.setCustomFeePolicy({
             computeFee: async (params)=>{
                 // Adapt provider-level params (with tokenIn/tokenOut)
@@ -21132,7 +21422,7 @@ registerKit(`${pkg$1.name}/${pkg$1.version}`);
 };
 
 var name = "@circle-fin/earn-kit";
-var version = "1.4.0";
+var version = "1.5.1";
 var pkg = {
 	name: name,
 	version: version};
@@ -22143,11 +22433,16 @@ const sourceAdapterContextSchema = zod.z.object({
  *
  * Validate the optional Kit Key field using the standard `apiKeySchema`
  * format (`KIT_KEY:<keyId>:<keySecret>`). When omitted, the SDK
- * operates in permissionless mode.
+ * operates in permissionless mode. `baseUrl` overrides the Earn Service
+ * endpoint (e.g. staging); `batchTransactions: false` opts out of atomic
+ * batched execution. Both are forwarded to the provider, so this `.strict()`
+ * schema must accept them or a valid config object is rejected.
  *
  * @internal
  */ const earnConfigSchema = zod.z.object({
-    kitKey: apiKeySchema.optional()
+    kitKey: apiKeySchema.optional(),
+    baseUrl: zod.z.string().optional(),
+    batchTransactions: zod.z.boolean().optional()
 }).strict();
 /**
  * Canonical decimal form: a leading digit with no leading zeros (a single