@circle-fin/app-kit 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @circle-fin/app-kit
 
+## 1.5.1
+
+### Patch Changes
+
+- Improves the error you get when attempting a Gateway spend with a smart-contract account (SCA) as the signer. The failure previously surfaced as a confusing `invalid integer value <nil>/<nil> for type uint256` response from the Circle Wallets backend; you now get a clear `INPUT_UNSUPPORTED_ACTION` error up front that points at the delegate workflow (`kit.unifiedBalance.addDelegate` + `kit.unifiedBalance.spend` with the delegate EOA as `from.address` and the SCA as `from.sourceAccount`).
+
 ## 1.5.0
 
 ### Minor Changes

package/index.cjs

@@ -15750,7 +15750,7 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain, statusCo
     return step;
 }
 
-var version$2 = "1.8.0";
+var version$2 = "1.8.1";
 var pkg$2 = {
 	version: version$2};
 
@@ -18149,7 +18149,7 @@ const createBridgeKit = (context) => {
 };
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.2.0";
+var version$1 = "1.2.1";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -22029,6 +22029,119 @@ function evmSigningData(burnIntent) {
     };
 }
 
+/**
+ * EIP-7702 delegation indicator. A 7702-delegated EOA's bytecode is
+ * `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.
+ *
+ * Spec: https://eips.ethereum.org/EIPS/eip-7702
+ */
+const EIP_7702_DELEGATION_PREFIX = '0xef0100';
+/**
+ * Assert that `address` on `chain` can sign Gateway burn intents.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @param adapter - Anything exposing {@link EvmAdapterLike.readBytecode}.
+ * @param address - Signer address to validate.
+ * @param chain - EVM chain where the signer lives.
+ * @throws {KitError} INPUT_UNSUPPORTED_ACTION when `address` is an SCA.
+ *
+ * @example
+ * ```typescript
+ * import { assertSignerIsEoa } from '@core/adapter-evm'
+ * import { Ethereum } from '@core/chains'
+ *
+ * await assertSignerIsEoa(adapter, '0xabc...', Ethereum)
+ * ```
+ */
+async function assertSignerIsEoa(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;
+    }
+    if (code === undefined ||
+        code === '0x' ||
+        code.toLowerCase().startsWith(EIP_7702_DELEGATION_PREFIX)) {
+        return;
+    }
+    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),
+            },
+        },
+    });
+}
+
+/**
+ * Duck-type test for an EVM adapter that exposes `readBytecode`.
+ *
+ * Used as a structural guard at package boundaries (e.g. the Circle Wallets
+ * hybrid adapter calling into a chain adapter, or the Gateway sign path
+ * receiving an arbitrary adapter implementation) where `instanceof EvmAdapter`
+ * is unreliable because each consumer bundles its own copy of the base class.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` is an object exposing a callable
+ *   `readBytecode` method, narrowed to {@link EvmAdapterLike}.
+ *
+ * @example
+ * ```typescript
+ * import { isEvmAdapterLike } from '@core/adapter-evm'
+ *
+ * if (isEvmAdapterLike(adapter)) {
+ *   const code = await adapter.readBytecode('0xabc...', chain)
+ * }
+ * ```
+ */
+function isEvmAdapterLike(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'readBytecode' in value &&
+        typeof value.readBytecode === 'function');
+}
+
 /**
  * Sign an EVM adapter group: batches all intents and produces a single
  * EIP-712 ECDSA signature.
@@ -22036,6 +22149,12 @@ function evmSigningData(burnIntent) {
  * For a single-intent group, `primaryType` is `'BurnIntent'`.
  * For multi-intent groups, `primaryType` is `'BurnIntentSet'`.
  *
+ * 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).
+ *
  * @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.
@@ -22056,6 +22175,22 @@ function evmSigningData(burnIntent) {
 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)
@@ -22325,9 +22460,10 @@ function getSolanaFeeRecipient() {
     return CIRCLE_FEE_RECIPIENT_SOLANA;
 }
 
-Buffer.from('gateway_minter');
-Buffer.from('gateway_minter_custody');
-Buffer.from('used_transfer_spec_hash');
+const enc = new TextEncoder();
+enc.encode('gateway_minter');
+enc.encode('gateway_minter_custody');
+enc.encode('used_transfer_spec_hash');
 
 async function executeAndWait$1(adapter, request, chain) {
     if (request.type === 'noop') {
@@ -30002,7 +30138,7 @@ const getSupportedChains$2 = (context, operationType, unifiedBalance) => {
 };
 
 var name = "@circle-fin/unified-balance-kit";
-var version = "1.1.0";
+var version = "1.1.1";
 var pkg = {
 	name: name,
 	version: version};
@@ -33307,13 +33443,20 @@ async function resolveAllocationsAndIntents(params, destChain, recipientAddress,
         const sourcesArray = rawSources.filter((s) => s != null);
         const networkType = destChain.isTestnet ? 'testnet' : 'mainnet';
         const balanceResults = await Promise.all(sourcesArray.map(async (source) => {
-            const querySource = {
-                adapter: source.adapter,
-            };
-            if (source.sourceAccount)
-                querySource['account'] = source.sourceAccount;
-            if ('address' in source && source.address) {
-                querySource['address'] = source.address;
+            // When sourceAccount is set (delegate flow), scope the balance
+            // query to the Gateway depositor — not the signer. Using the
+            // address-only path bypasses adapter address resolution, which
+            // would otherwise return the signer's balance (developer-
+            // controlled) or reject an explicit address (user-controlled).
+            let querySource;
+            if (source.sourceAccount) {
+                querySource = { address: source.sourceAccount };
+            }
+            else {
+                querySource = { adapter: source.adapter };
+                if ('address' in source && source.address) {
+                    querySource['address'] = source.address;
+                }
             }
             return getBalances$1({
                 token: params.token,

package/index.mjs

@@ -15743,7 +15743,7 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain, statusCo
     return step;
 }
 
-var version$2 = "1.8.0";
+var version$2 = "1.8.1";
 var pkg$2 = {
 	version: version$2};
 
@@ -18142,7 +18142,7 @@ const createBridgeKit = (context) => {
 };
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.2.0";
+var version$1 = "1.2.1";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -22022,6 +22022,119 @@ function evmSigningData(burnIntent) {
     };
 }
 
+/**
+ * EIP-7702 delegation indicator. A 7702-delegated EOA's bytecode is
+ * `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.
+ *
+ * Spec: https://eips.ethereum.org/EIPS/eip-7702
+ */
+const EIP_7702_DELEGATION_PREFIX = '0xef0100';
+/**
+ * Assert that `address` on `chain` can sign Gateway burn intents.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @param adapter - Anything exposing {@link EvmAdapterLike.readBytecode}.
+ * @param address - Signer address to validate.
+ * @param chain - EVM chain where the signer lives.
+ * @throws {KitError} INPUT_UNSUPPORTED_ACTION when `address` is an SCA.
+ *
+ * @example
+ * ```typescript
+ * import { assertSignerIsEoa } from '@core/adapter-evm'
+ * import { Ethereum } from '@core/chains'
+ *
+ * await assertSignerIsEoa(adapter, '0xabc...', Ethereum)
+ * ```
+ */
+async function assertSignerIsEoa(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;
+    }
+    if (code === undefined ||
+        code === '0x' ||
+        code.toLowerCase().startsWith(EIP_7702_DELEGATION_PREFIX)) {
+        return;
+    }
+    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),
+            },
+        },
+    });
+}
+
+/**
+ * Duck-type test for an EVM adapter that exposes `readBytecode`.
+ *
+ * Used as a structural guard at package boundaries (e.g. the Circle Wallets
+ * hybrid adapter calling into a chain adapter, or the Gateway sign path
+ * receiving an arbitrary adapter implementation) where `instanceof EvmAdapter`
+ * is unreliable because each consumer bundles its own copy of the base class.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` is an object exposing a callable
+ *   `readBytecode` method, narrowed to {@link EvmAdapterLike}.
+ *
+ * @example
+ * ```typescript
+ * import { isEvmAdapterLike } from '@core/adapter-evm'
+ *
+ * if (isEvmAdapterLike(adapter)) {
+ *   const code = await adapter.readBytecode('0xabc...', chain)
+ * }
+ * ```
+ */
+function isEvmAdapterLike(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'readBytecode' in value &&
+        typeof value.readBytecode === 'function');
+}
+
 /**
  * Sign an EVM adapter group: batches all intents and produces a single
  * EIP-712 ECDSA signature.
@@ -22029,6 +22142,12 @@ function evmSigningData(burnIntent) {
  * For a single-intent group, `primaryType` is `'BurnIntent'`.
  * For multi-intent groups, `primaryType` is `'BurnIntentSet'`.
  *
+ * 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).
+ *
  * @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.
@@ -22049,6 +22168,22 @@ function evmSigningData(burnIntent) {
 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)
@@ -22318,9 +22453,10 @@ function getSolanaFeeRecipient() {
     return CIRCLE_FEE_RECIPIENT_SOLANA;
 }
 
-Buffer.from('gateway_minter');
-Buffer.from('gateway_minter_custody');
-Buffer.from('used_transfer_spec_hash');
+const enc = new TextEncoder();
+enc.encode('gateway_minter');
+enc.encode('gateway_minter_custody');
+enc.encode('used_transfer_spec_hash');
 
 async function executeAndWait$1(adapter, request, chain) {
     if (request.type === 'noop') {
@@ -29995,7 +30131,7 @@ const getSupportedChains$2 = (context, operationType, unifiedBalance) => {
 };
 
 var name = "@circle-fin/unified-balance-kit";
-var version = "1.1.0";
+var version = "1.1.1";
 var pkg = {
 	name: name,
 	version: version};
@@ -33300,13 +33436,20 @@ async function resolveAllocationsAndIntents(params, destChain, recipientAddress,
         const sourcesArray = rawSources.filter((s) => s != null);
         const networkType = destChain.isTestnet ? 'testnet' : 'mainnet';
         const balanceResults = await Promise.all(sourcesArray.map(async (source) => {
-            const querySource = {
-                adapter: source.adapter,
-            };
-            if (source.sourceAccount)
-                querySource['account'] = source.sourceAccount;
-            if ('address' in source && source.address) {
-                querySource['address'] = source.address;
+            // When sourceAccount is set (delegate flow), scope the balance
+            // query to the Gateway depositor — not the signer. Using the
+            // address-only path bypasses adapter address resolution, which
+            // would otherwise return the signer's balance (developer-
+            // controlled) or reject an explicit address (user-controlled).
+            let querySource;
+            if (source.sourceAccount) {
+                querySource = { address: source.sourceAccount };
+            }
+            else {
+                querySource = { adapter: source.adapter };
+                if ('address' in source && source.address) {
+                    querySource['address'] = source.address;
+                }
             }
             return getBalances$1({
                 token: params.token,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circle-fin/app-kit",
-  "version": "1.5.0",
+  "version": "1.5.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,10 +36,10 @@
   "module": "./index.mjs",
   "types": "./index.d.ts",
   "dependencies": {
-    "@circle-fin/unified-balance-kit": "1.1.0",
-    "@circle-fin/provider-gateway-v1": "1.0.3",
+    "@circle-fin/unified-balance-kit": "1.1.1",
+    "@circle-fin/provider-gateway-v1": "1.0.4",
     "@circle-fin/bridge-kit": "1.10.0",
-    "@circle-fin/swap-kit": "1.2.0",
+    "@circle-fin/swap-kit": "1.2.1",
     "zod": "3.25.67",
     "@ethersproject/address": "^5.8.0",
     "@ethersproject/bytes": "^5.8.0",