@circle-fin/app-kit 1.10.0 → 1.12.0

package/unifiedBalance.mjs

@@ -16,6 +16,17 @@
  * limitations under the License.
  */
 
+// Buffer polyfill setup - executes before any other code
+// Ensures globalThis.Buffer is available for Solana libraries
+import { Buffer } from 'buffer';
+if (typeof globalThis !== 'undefined' && typeof globalThis.Buffer === 'undefined') {
+    globalThis.Buffer = Buffer;
+}
+if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
+    window.Buffer = Buffer;
+}
+
+
 import { z } from 'zod';
 import { PublicKey } from '@solana/web3.js';
 import 'bn.js';
@@ -41,6 +52,27 @@ import { getAddress } from '@ethersproject/address';
  * }
  * ```
  */ const isNodeEnvironment = ()=>typeof process !== 'undefined' && typeof process.versions === 'object' && typeof process.versions.node === 'string';
+/**
+ * Return the SDK User-Agent request header only when running in Node.js.
+ *
+ * Browsers forbid manually setting `User-Agent`, and a custom fallback header
+ * can trigger CORS preflight. Non-Node server runtimes also omit this optional
+ * attribution header because they cannot set it reliably.
+ *
+ * @returns A User-Agent header in Node.js, or an empty object otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { getNodeUserAgentHeader } from '@core/utils'
+ *
+ * const headers = {
+ *   'Content-Type': 'application/json',
+ *   ...getNodeUserAgentHeader(),
+ * }
+ * ```
+ */ const getNodeUserAgentHeader = ()=>isNodeEnvironment() ? {
+        'User-Agent': getUserAgent()
+    } : {};
 /**
  * Detect the runtime environment and return a shortened identifier.
  *
@@ -626,11 +658,6 @@ class KitError extends Error {
         name: 'INPUT_UNSUPPORTED_TOKEN',
         type: 'INPUT'
     },
-    /** Action not supported by this adapter / ecosystem */ UNSUPPORTED_ACTION: {
-        code: 1008,
-        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',
@@ -2287,6 +2314,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 = {}));
@@ -2340,6 +2369,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";
@@ -2365,6 +2395,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) {
@@ -4912,7 +4943,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',
@@ -5777,6 +5809,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
@@ -5896,6 +6026,8 @@ var Chains = /*#__PURE__*/Object.freeze({
   WorldChainSepolia: WorldChainSepolia,
   XDC: XDC,
   XDCApothem: XDCApothem,
+  XLayer: XLayer,
+  XLayerTestnet: XLayerTestnet,
   ZKSyncEra: ZKSyncEra,
   ZKSyncEraSepolia: ZKSyncEraSepolia
 });
@@ -7080,13 +7212,12 @@ const swapTokenEnumSchema = z.enum([
         headers: {
             ...DEFAULT_CONFIG.headers,
             ...config.headers ?? {},
-            // In browser environments, directly setting the 'User-Agent' or similar headers is restricted and may be ignored or cause errors.
-            // This is why we use the 'X-User-Agent' header instead.
-            ...typeof window === 'undefined' ? {
-                'User-Agent': getUserAgent()
-            } : {
-                'X-User-Agent': getUserAgent()
-            }
+            // Browsers forbid setting a user-agent request header, and the custom
+            // fallback header the SDK used instead trips CORS preflight against the
+            // Circle APIs (it isn't in their `Access-Control-Allow-Headers`),
+            // blocking the request. So send the SDK user agent only in Node;
+            // browsers omit it entirely.
+            ...getNodeUserAgentHeader()
         }
     };
     let lastError;
@@ -7849,6 +7980,7 @@ function parseOrThrow(value, schema, context) {
         [Blockchain.Unichain]: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
         [Blockchain.World_Chain]: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
         [Blockchain.XDC]: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
+        [Blockchain.X_Layer]: '0xB6CEceAB302E2E4948951eE7843FC24E92933061',
         [Blockchain.ZKSync_Era]: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
         // =========================================================================
         // Testnets (alphabetically sorted)
@@ -7883,6 +8015,7 @@ function parseOrThrow(value, schema, context) {
         [Blockchain.Unichain_Sepolia]: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
         [Blockchain.World_Chain_Sepolia]: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
         [Blockchain.XDC_Apothem]: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
+        [Blockchain.X_Layer_Testnet]: '0xDec90b78111Ba2fc6FC6d84d8B9ec159A2d4b9B3',
         [Blockchain.ZKSync_Sepolia]: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853'
     }
 };
@@ -8358,6 +8491,7 @@ function parseOrThrow(value, schema, context) {
     if (payload.tokenIn !== undefined) safe['tokenIn'] = payload.tokenIn;
     if (payload.tokenOut !== undefined) safe['tokenOut'] = payload.tokenOut;
     if (payload.txHash !== undefined) safe['txHash'] = payload.txHash;
+    if (payload.correlationId !== undefined) safe['correlationId'] = payload.correlationId;
     if (payload.errorDetails !== undefined) {
         const errorDetails = {
             ...payload.errorDetails.errorCode !== undefined && {
@@ -8428,18 +8562,15 @@ function parseOrThrow(value, schema, context) {
         timeoutHandle.unref();
     }
     try {
-        const isNode = isNodeEnvironment();
-        const userAgent = getUserAgent();
         await fetch(getLogsUrl(), {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
-                // Browser restricts setting User-Agent; use X-User-Agent instead.
-                ...isNode ? {
-                    'User-Agent': userAgent
-                } : {
-                    'X-User-Agent': userAgent
-                }
+                // Browsers forbid setting a user-agent request header, and the custom
+                // fallback header the SDK used instead trips CORS preflight (it isn't
+                // in the telemetry endpoint's `Access-Control-Allow-Headers`), so send
+                // it only in Node; browsers omit it entirely.
+                ...getNodeUserAgentHeader()
             },
             body: JSON.stringify(toSafePayload(payload)),
             signal: controller.signal
@@ -8652,7 +8783,7 @@ function parseOrThrow(value, schema, context) {
         // discards the stack trace, nested `cause`, and any custom Error
         // properties — exactly the context an on-call needs when a
         // resolver-closure regression triggers this path.
-        console.warn(`[stablecoin-kits telemetry] dropped error event '${eventType}':`, cause);
+        console.warn(`[stablecoin-kits telemetry] dropped event '${eventType}':`, cause);
     } catch  {
     // console.warn itself throwing is the user's environment; nothing more we
     // can do without risking the original operation error.
@@ -8668,7 +8799,9 @@ function parseOrThrow(value, schema, context) {
         sdkVersion: config.sdkVersion,
         eventType,
         timestamp: new Date().toISOString(),
-        errorDetails,
+        ...errorDetails !== undefined && {
+            errorDetails
+        },
         clientContext: buildClientContext(),
         ...context?.sourceChain != null && {
             sourceChain: context.sourceChain
@@ -8684,6 +8817,9 @@ function parseOrThrow(value, schema, context) {
         },
         ...context?.txHash != null && {
             txHash: context.txHash
+        },
+        ...context?.correlationId != null && {
+            correlationId: context.correlationId
         }
     };
 }
@@ -8745,7 +8881,7 @@ function parseOrThrow(value, schema, context) {
 }
 
 var name = "@circle-fin/unified-balance-kit";
-var version = "1.3.0";
+var version = "1.4.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -12026,72 +12162,55 @@ function evmSigningData(burnIntent) {
  * `0xef0100` followed by the 20-byte delegate address (23 bytes total).
  * The underlying secp256k1 key still produces `ecrecover`-verifiable
  * signatures, so for Gateway's purposes a 7702-delegated address is
- * an EOA, not an SCA.
+ * an EOA, not a contract signer.
  *
  * Spec: https://eips.ethereum.org/EIPS/eip-7702
  */ const EIP_7702_DELEGATION_PREFIX = '0xef0100';
 /**
- * Assert that `address` on `chain` can sign Gateway burn intents.
+ * Determine whether `address` on `chain` signs as a contract (ERC-1271)
+ * rather than as an EOA.
  *
- * Gateway verifies burn-intent signatures with plain `ecrecover` (see
- * `evm-gateway-contracts/src/lib/EIP712Domain.sol`). Smart-contract
- * accounts (SCAs) produce signatures over wrapped hashes (ERC-1271 /
- * ERC-6492 / ERC-6900 replay-safe hashes) that Gateway cannot verify.
- * Additionally, the Circle Wallets backend rejects SCA typed-data signing
- * against Gateway's chainId-less domain with an opaque
- * `invalid integer value <nil>/<nil> for type uint256` error.
+ * Gateway validates burn-intent signatures two ways: a static `ecrecover`
+ * check for EOAs, and — for requests that carry `contractSigner: true` —
+ * an offchain `isValidSignature` simulation against the signing contract
+ * (ERC-1271). Gateway does not infer which one to use, so the caller must
+ * declare it. This detects the contract case from on-chain bytecode.
  *
- * EIP-7702-delegated EOAs are exempt: they expose non-empty bytecode
- * (`0xef0100<delegate>`) but the underlying secp256k1 key still produces
- * `ecrecover`-verifiable signatures, so Gateway accepts them.
+ * EIP-7702-delegated EOAs are treated as EOAs: they expose non-empty
+ * bytecode (`0xef0100<delegate>`) but the underlying secp256k1 key still
+ * produces `ecrecover`-verifiable signatures, so the cheaper EOA path
+ * stays correct for them.
  *
- * When the signer is a true SCA, raises an `INPUT_UNSUPPORTED_ACTION`
- * error directing the caller to register an EOA delegate against the
- * SCA and then submit the spend with the delegate EOA as the signer
- * and the SCA as the source account. See the unified-balance / Gateway
- * docs for the exact API.
- *
- * If bytecode cannot be read (RPC failure, etc.) the pre-check is
- * skipped and downstream signing surfaces its own error — a warning is
- * logged so the skip is diagnosable.
+ * If bytecode cannot be read (RPC failure, etc.) the address is reported
+ * as an EOA and a warning is logged so the fallback is diagnosable. A
+ * genuine contract signer misreported this way is rejected by Gateway with
+ * an invalid-signature error rather than silently mis-attested.
  *
  * @param adapter - Anything exposing {@link EvmAdapterLike.readBytecode}.
- * @param address - Signer address to validate.
+ * @param address - Signer address to classify.
  * @param chain - EVM chain where the signer lives.
- * @throws {KitError} INPUT_UNSUPPORTED_ACTION when `address` is an SCA.
+ * @returns `true` when the signer is a contract account and the transfer
+ *   request must set `contractSigner: true`; `false` otherwise.
  *
  * @example
  * ```typescript
- * import { assertSignerIsEoa } from '@core/adapter-evm'
+ * import { isContractSigner } from '@core/adapter-evm'
  * import { Ethereum } from '@core/chains'
  *
- * await assertSignerIsEoa(adapter, '0xabc...', Ethereum)
+ * const useErc1271 = await isContractSigner(adapter, '0xabc...', Ethereum)
  * ```
- */ async function assertSignerIsEoa(adapter, address, chain) {
+ */ async function isContractSigner(adapter, address, chain) {
     let code;
     try {
         code = await adapter.readBytecode(address, chain);
     } catch (err) {
-        console.warn(`[gateway] assertSignerIsEoa skipped (readBytecode failed for ` + `${address} on ${chain.name}): ` + (err instanceof Error ? err.message : String(err)));
-        return;
+        console.warn(`[gateway] isContractSigner defaulting to EOA (readBytecode failed ` + `for ${address} on ${chain.name}): ` + (err instanceof Error ? err.message : String(err)));
+        return false;
     }
     if (code === undefined || code === '0x' || code.toLowerCase().startsWith(EIP_7702_DELEGATION_PREFIX)) {
-        return;
+        return false;
     }
-    throw new KitError({
-        ...InputError.UNSUPPORTED_ACTION,
-        recoverability: 'FATAL',
-        message: `Gateway burn-intent signing requires an EOA signer (Gateway ` + `verifies signatures with ecrecover and does not support ERC-1271). ` + `The signer ${address} on ${chain.name} has on-chain bytecode, ` + `indicating it is a smart-contract account (SCA). Register an EOA ` + `delegate against the SCA, then submit the spend with the delegate ` + `EOA as the signer and the SCA as the source account. See DEVX-2774.`,
-        cause: {
-            trace: {
-                operation: 'signEvmIntentGroup.assertSignerIsEoa',
-                address,
-                chain: chain.name,
-                bytecodeBytes: (code.length - 2) / 2,
-                bytecodePrefix: code.slice(0, 12)
-            }
-        }
-    });
+    return true;
 }
 
 /**
@@ -12118,78 +12237,177 @@ function evmSigningData(burnIntent) {
     return typeof value === 'object' && value !== null && 'readBytecode' in value && typeof value.readBytecode === 'function';
 }
 
+function resolveIntentChain(group, intent) {
+    const sourceDomain = intent.spec.sourceDomain;
+    const chain = group.chainsByDomain.get(sourceDomain);
+    if (chain !== undefined) return chain;
+    throw createValidationFailedError$1('intent.spec.sourceDomain', sourceDomain, `No source chain found for Gateway domain ${String(sourceDomain)}`);
+}
+function normalizeSignatureResult(result) {
+    if (typeof result === 'string') {
+        return {
+            signature: result,
+            contractSigner: false
+        };
+    }
+    if (typeof result === 'object' && result !== null && 'signature' in result && typeof result.signature === 'string') {
+        return {
+            signature: result.signature,
+            contractSigner: 'contractSigner' in result && result.contractSigner === true
+        };
+    }
+    throw createValidationFailedError$1('signature', result, 'must be a signature string or an object containing a signature string');
+}
+function validateGroupIntents(intents) {
+    evmSigningData(intents);
+}
+function collectChainsByDomain(group) {
+    const chainsByDomain = new Map();
+    for (const intent of group.intents){
+        chainsByDomain.set(intent.spec.sourceDomain, resolveIntentChain(group, intent));
+    }
+    return chainsByDomain;
+}
+async function classifySignerTypes(group, chainsByDomain) {
+    const { adapter, address } = group;
+    // Duck-typed on readBytecode rather than `instanceof EvmAdapter` because
+    // each consumer package bundles its own copy of the base class and the
+    // `instanceof` identity check fails across package boundaries.
+    // Empty strings are rejected to avoid calling eth_getCode('') on the RPC.
+    const hasResolvedSigner = typeof address === 'string' && address.length > 0;
+    const signerTypes = await Promise.all([
+        ...chainsByDomain
+    ].map(async ([sourceDomain, sourceChain])=>{
+        const contractSigner = hasResolvedSigner && sourceChain.type === 'evm' && isEvmAdapterLike(adapter) ? await isContractSigner(adapter, address, sourceChain) : false;
+        return [
+            sourceDomain,
+            contractSigner
+        ];
+    }));
+    return new Map(signerTypes);
+}
+function createSigningUnits(group, signerTypeByDomain) {
+    const contractUnitsByDomain = new Map();
+    let eoaUnit;
+    for (const [index, intent] of group.intents.entries()){
+        const sourceDomain = intent.spec.sourceDomain;
+        const contractSigner = signerTypeByDomain.get(sourceDomain) ?? false;
+        if (contractSigner) {
+            const existingUnit = contractUnitsByDomain.get(sourceDomain);
+            if (existingUnit === undefined) {
+                contractUnitsByDomain.set(sourceDomain, {
+                    intents: [
+                        intent
+                    ],
+                    chain: resolveIntentChain(group, intent),
+                    contractSigner: true,
+                    firstIntentIndex: index
+                });
+            } else {
+                existingUnit.intents.push(intent);
+            }
+        } else {
+            eoaUnit ??= {
+                intents: [],
+                chain: resolveIntentChain(group, intent),
+                contractSigner: false,
+                firstIntentIndex: index
+            };
+            eoaUnit.intents.push(intent);
+        }
+    }
+    const signingUnits = [
+        ...contractUnitsByDomain.values()
+    ];
+    if (eoaUnit !== undefined) signingUnits.push(eoaUnit);
+    signingUnits.sort((a, b)=>a.firstIntentIndex - b.firstIntentIndex);
+    return signingUnits;
+}
+async function signUnit(group, unit) {
+    const { adapter, address } = group;
+    const firstIntent = unit.intents[0];
+    const typedData = unit.intents.length === 1 && firstIntent !== undefined ? evmSigningData(firstIntent) : evmSigningData(unit.intents);
+    const operationContext = address === undefined ? {
+        chain: unit.chain
+    } : {
+        chain: unit.chain,
+        address
+    };
+    const signRequest = await adapter.prepareAction('gateway.v1.signBurnIntents', {
+        typedData,
+        chain: unit.chain
+    }, operationContext);
+    const result = normalizeSignatureResult(await signRequest.execute());
+    return {
+        intents: unit.intents,
+        signature: result.signature,
+        contractSigner: result.contractSigner || unit.contractSigner
+    };
+}
+async function signUnits(group, signingUnits) {
+    const signedSets = [];
+    // Keep wallet prompts deterministic. Multiple adapter groups can still sign
+    // in parallel, but one signer is asked for its chain-bound signatures in
+    // source-intent order.
+    for (const unit of signingUnits){
+        signedSets.push(await signUnit(group, unit));
+    }
+    return signedSets;
+}
 /**
- * Sign an EVM adapter group: batches all intents and produces a single
- * EIP-712 ECDSA signature.
+ * Sign an EVM adapter group.
  *
- * For a single-intent group, `primaryType` is `'BurnIntent'`.
- * For multi-intent groups, `primaryType` is `'BurnIntentSet'`.
+ * EOA intents remain batched into one EIP-712 `BurnIntentSet`. ERC-1271
+ * intents are grouped and signed per source chain because smart accounts
+ * commonly include `chainId` in their replay-safe signature hash.
+ * All returned entries can still be submitted together in one atomic Gateway
+ * transfer request.
  *
- * Before signing, asserts that the signer address is an EOA. Gateway
- * verifies burn-intent signatures with plain `ecrecover` (no ERC-1271
- * fallback), so signatures produced by smart-contract accounts (SCAs)
- * cannot be verified. When an SCA is detected, a clear error is raised
- * directing the caller to the delegate workflow (DEVX-2774).
+ * Before signing, classifies the signer as an EOA or a contract account.
+ * Gateway validates EOA signatures with `ecrecover` and contract-account
+ * signatures with ERC-1271, but it does not infer which one applies — the
+ * transfer request has to declare it. The returned `contractSigner` flag
+ * carries that decision through to `buildTransferRequestBody`.
  *
  * @param group - The adapter group containing the adapter, chain, and
  *   burn intents to sign.
- * @returns A signed set with the intents and the ECDSA signature.
+ * @returns Signed entries with their intents, signatures, and Gateway signer
+ *   validation mode.
+ * @throws KitError when an intent has no source-chain mapping or a signing
+ *   action returns an invalid signature shape.
  *
  * @example
  * ```typescript
  * import { signEvmIntentGroup } from '@core/adapter-evm'
  *
- * const signedSet = await signEvmIntentGroup({
+ * const signedSets = await signEvmIntentGroup({
  *   adapter: evmAdapter,
  *   chain: ethereumChain,
  *   intents: [burnIntent1, burnIntent2],
+ *   chainsByDomain: new Map([
+ *     [0, ethereumChain],
+ *     [6, baseChain],
+ *   ]),
  *   address: '0x...',
  * })
- * console.log(signedSet.signature)
+ * console.log(signedSets)
  * ```
  */ async function signEvmIntentGroup(group) {
-    const { adapter, intents: groupIntents, chain, address } = group;
-    const operationContext = address === undefined ? {
-        chain
-    } : {
-        chain,
-        address
-    };
-    // Gateway verifies burn-intent signatures with plain ecrecover. An SCA
-    // signer silently produces a signature over a wrapped hash that Gateway
-    // cannot verify, and Circle Wallets' KMS rejects the typed data up front
-    // with an opaque `<nil>/<nil>` error. Short-circuit with a clear message
-    // when we can detect bytecode at the signer address. See DEVX-2774.
-    //
-    // Duck-typed on readBytecode rather than `instanceof EvmAdapter` because
-    // each consumer package bundles its own copy of the base class and the
-    // `instanceof` identity check fails across package boundaries.
-    //
-    // Empty string is defended against because assertSignerIsEoa would
-    // otherwise call eth_getCode('') on the RPC.
-    const hasResolvedSigner = typeof address === 'string' && address.length > 0;
-    if (hasResolvedSigner && chain.type === 'evm' && isEvmAdapterLike(adapter)) {
-        await assertSignerIsEoa(adapter, address, chain);
-    }
-    const firstIntent = groupIntents[0];
-    const typedData = groupIntents.length === 1 && firstIntent ? evmSigningData(firstIntent) : evmSigningData(groupIntents);
-    const signRequest = await adapter.prepareAction('gateway.v1.signBurnIntents', {
-        typedData,
-        chain
-    }, operationContext);
-    const sig = await signRequest.execute();
-    return {
-        intents: groupIntents,
-        signature: sig
-    };
+    // Validate the collection before doing bytecode reads or asking a wallet
+    // to sign. evmSigningData owns the canonical BurnIntent validation.
+    validateGroupIntents(group.intents);
+    const chainsByDomain = collectChainsByDomain(group);
+    const signerTypeByDomain = await classifySignerTypes(group, chainsByDomain);
+    const signingUnits = createSigningUnits(group, signerTypeByDomain);
+    return await signUnits(group, signingUnits);
 }
 
 /**
  * Add an EVM intent into the batched EVM group map.
  *
  * On EVM, all intents for the same adapter are batched into a single
- * group so that they can be signed in one EIP-712 `BurnIntentSet`
- * operation.
+ * group. The signing step uses `chainsByDomain` to preserve EOA batching
+ * while signing ERC-1271 intents separately on their source chains.
  *
  * @param intent - The burn intent to group.
  * @param alloc - The allocation that resolved to this intent.
@@ -12206,6 +12424,7 @@ function evmSigningData(burnIntent) {
     const existing = evmGroups.get(alloc.adapter);
     if (existing) {
         existing.intents.push(intent);
+        existing.chainsByDomain.set(alloc.chain.gateway.domain, alloc.chain);
     } else {
         evmGroups.set(alloc.adapter, {
             adapter: alloc.adapter,
@@ -12213,6 +12432,12 @@ function evmSigningData(burnIntent) {
             intents: [
                 intent
             ],
+            chainsByDomain: new Map([
+                [
+                    alloc.chain.gateway.domain,
+                    alloc.chain
+                ]
+            ]),
             address: alloc.sourceSigner
         });
     }
@@ -13738,7 +13963,8 @@ function throwNetworkMismatch(expected, actual) {
     };
 }
 /**
- * Group intents by adapter and chain for signing (Solana one-per-intent, EVM batched by adapter).
+ * Group intents for signing (Solana one-per-intent, EVM batched by adapter
+ * with every source chain retained by Gateway domain).
  *
  * @param intents - Burn intents from estimate response.
  * @param allocations - Normalized allocations used to map domain → adapter/chain.
@@ -16631,22 +16857,32 @@ const DEFAULT_GAS_FEE = parseUnits('0.1', USDC_DECIMALS);
  *
  * Single-intent sets become one burnIntent + signature; multi-intent sets become burnIntentSet + signature.
  *
+ * Sets flagged `contractSigner` carry `contractSigner: true`, which tells
+ * Gateway to validate the signature with ERC-1271 (an offchain
+ * `isValidSignature` simulation) instead of `ecrecover`. The flag is
+ * omitted for EOA signers so their payloads stay byte-identical.
+ *
  * @param signedSets - Signed intent sets (intents + signature per signer).
  * @returns Array of transfer payloads for POST /v1/transfer.
  */ function buildTransferRequestBody(signedSets) {
     return signedSets.map((set)=>{
         const firstIntent = set.intents[0];
+        const contractSigner = set.contractSigner === true ? {
+            contractSigner: true
+        } : {};
         if (set.intents.length === 1 && firstIntent) {
             return {
                 burnIntent: serializeBurnIntent(firstIntent),
-                signature: set.signature
+                signature: set.signature,
+                ...contractSigner
             };
         }
         return {
             burnIntentSet: {
                 intents: set.intents.map(serializeBurnIntent)
             },
-            signature: set.signature
+            signature: set.signature,
+            ...contractSigner
         };
     });
 }
@@ -17009,11 +17245,16 @@ const BPS_DIVISOR = 100_000n;
     return required;
 }
 
+function requireEvmChainsByDomain(group) {
+    if (group.chainsByDomain !== undefined) return group.chainsByDomain;
+    throw createValidationFailedError$1('adapterGroup.chainsByDomain', group.chainsByDomain, 'must be provided for an EVM adapter group');
+}
 /**
- * Sign each adapter group: Solana one intent per signature, EVM batch per adapter.
+ * Sign each adapter group: Solana one intent per signature, and EVM either
+ * batched for EOAs or split by source chain for ERC-1271 signers.
  *
  * @param adapterGroups - Groups from groupIntentsByAdapter.
- * @returns Promise of signed sets (intents + signature) for buildTransferRequestBody.
+ * @returns Promise of signed sets for buildTransferRequestBody.
  *
  * @example
  * ```typescript
@@ -17026,9 +17267,10 @@ const BPS_DIVISOR = 100_000n;
         if (group.chain.type === 'solana') {
             return signSolanaIntentGroup(group);
         }
-        return [
-            await signEvmIntentGroup(group)
-        ];
+        return await signEvmIntentGroup({
+            ...group,
+            chainsByDomain: requireEvmChainsByDomain(group)
+        });
     }));
     return nested.flat();
 }
@@ -17678,7 +17920,8 @@ async function runSpendNormalPath(params, destChain, useForwarder, dispatcher, s
             signedSetCount: signedSets.length,
             signatures: signedSets.map((s)=>({
                     intentCount: s.intents.length,
-                    signature: s.signature
+                    signature: s.signature,
+                    contractSigner: s.contractSigner === true
                 }))
         }
     });
@@ -20423,7 +20666,11 @@ const removeFundParamsSchema = z.object({
 // Remove Fund Operations
 // ---------------------------------------------------------------------------
 /**
- * Kick off a delayed fund removal from an account.
+ * Kick off a delayed recovery fund removal from an account.
+ *
+ * Use `initiateRemoveFund` only as a trustless fallback when the normal spend
+ * flow is unavailable. For day-to-day movement out of a Unified Balance, use
+ * `spend`.
  *
  * Validates `from` and `amount`, resolves the chain and token via
  * {@link resolveRemoveFundParams}, selects the matching provider, then calls
@@ -20460,7 +20707,10 @@ const removeFundParamsSchema = z.object({
     return provider.initiateRemoveFund(resolved);
 }
 /**
- * Complete a fund removal once the 7-day activation period has passed.
+ * Complete a recovery fund removal once the 7-day withdrawal delay has passed.
+ *
+ * Use `removeFund` only as a trustless fallback when the normal spend flow is
+ * unavailable. For day-to-day movement out of a Unified Balance, use `spend`.
  *
  * Validates `from`, resolves the chain and token via
  * {@link resolveRemoveFundParams}, selects the matching provider, then calls
@@ -20549,13 +20799,18 @@ const removeFundParamsSchema = z.object({
 /** SDK name used in telemetry payloads. */ const SDK_NAME = resolveKitSdkName(pkg.name);
 /**
  * A high-level class-based interface for cross-chain USDC deposits,
- * spending, balance queries, delegation management, and withdrawals.
+ * spending, balance queries, delegation management, and recovery fund removals.
  *
  * UnifiedBalanceKit provides a familiar class-based API for developers who
  * prefer traditional object-oriented patterns. The class maintains an
  * internal context and provides methods that delegate to the standalone
  * operation functions exported by this package.
  *
+ * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+ * trustless recovery path for situations where the normal spend flow is
+ * unavailable, and it requires a 7-day withdrawal delay before funds can be
+ * removed.
+ *
  * @remarks
  * For functional usage, import and use the operations directly:
  * ```typescript
@@ -20776,7 +21031,11 @@ const removeFundParamsSchema = z.object({
         });
     }
     /**
-   * Kick off a delayed fund removal from an account.
+   * Kick off a delayed recovery fund removal from an account.
+   *
+   * Use this only as a trustless fallback when the normal spend flow is
+   * unavailable. For day-to-day movement out of a Unified Balance, use
+   * `spend`.
    *
    * @param params - The account owner's adapter context, amount, and
    *   optional token type.
@@ -20790,7 +21049,12 @@ const removeFundParamsSchema = z.object({
         });
     }
     /**
-   * Complete a fund removal once the activation period has passed.
+   * Complete a recovery fund removal once the 7-day withdrawal delay has
+   * passed.
+   *
+   * Use this only as a trustless fallback when the normal spend flow is
+   * unavailable. For day-to-day movement out of a Unified Balance, use
+   * `spend`.
    *
    * @param params - The account owner context matching the original
    *   fund removal initiation.
@@ -20917,6 +21181,11 @@ registerKit(`${pkg.name}/${pkg.version}`);
  * Internally holds a persistent {@link UnifiedBalanceKit} instance so that
  * event dispatchers and custom fee policies are preserved across calls.
  *
+ * Use {@link AppKitUnifiedBalance.spend} for normal movement out of a Unified
+ * Balance. {@link AppKitUnifiedBalance.removeFund} is a trustless recovery path
+ * for situations where the normal spend flow is unavailable, and it requires a
+ * 7-day withdrawal delay after {@link AppKitUnifiedBalance.initiateRemoveFund}.
+ *
  * @example
  * ```typescript
  * import { AppKit } from '@circle-fin/app-kit'
@@ -21128,7 +21397,12 @@ registerKit(`${pkg.name}/${pkg.version}`);
         return this.kit.removeDelegate(params);
     }
     /**
-   * Kick off a delayed fund removal from an account.
+   * Initiate a trustless recovery removal from an account.
+   *
+   * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+   * recovery path for situations where the normal spend flow is unavailable.
+   * Calling this method starts the 7-day withdrawal delay before the removal can
+   * be completed.
    *
    * @param params - The account owner's adapter context, amount, and token.
    * @returns Promise resolving to the initiation details.
@@ -21147,11 +21421,16 @@ registerKit(`${pkg.name}/${pkg.version}`);
         return this.kit.initiateRemoveFund(params);
     }
     /**
-   * Complete a fund removal once the activation period has passed.
+   * Complete a trustless recovery removal after the withdrawal delay.
+   *
+   * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+   * recovery path for situations where the normal spend flow is unavailable.
+   * Both EVM and Solana removals require a 7-day withdrawal delay after
+   * `initiateRemoveFund` before funds can be removed.
    *
    * @param params - The account owner context matching the original initiation.
    * @returns Promise resolving to the fund removal details.
-   * @throws {KitError} If the activation period has not elapsed or the
+   * @throws {KitError} If the withdrawal delay has not elapsed or the
    *   on-chain transaction fails.
    *
    * @example