@circle-fin/app-kit 1.15.2 → 1.16.0

package/unifiedBalance.cjs

@@ -1341,6 +1341,34 @@ let activeRedactor = defaultMessageRedactor;
     return redactErrorMessage(String(error));
 }
 
+/**
+ * Render an object value for an error message without letting the rendering
+ * itself throw.
+ *
+ * `JSON.stringify` rejects `BigInt` and circular structures, and a rejected
+ * value is exactly the kind of thing a validation error is built from: an
+ * on-chain read or a receipt log carries `bigint` fields, so serializing one
+ * naively replaces the intended error with a `TypeError`.
+ *
+ * @param value - The value to render.
+ * @returns A JSON string with `bigint` fields stringified, or
+ *   `'[unserializable object]'` if serialization still fails.
+ * @throws Never; serialization failures are caught and rendered as a fallback string.
+ * @example
+ * ```typescript
+ * import { describeObjectValue } from '@core/errors'
+ *
+ * describeObjectValue({ amount: 1n })
+ * // '{"amount":"1"}'
+ * ```
+ */ function describeObjectValue(value) {
+    try {
+        return JSON.stringify(value, (_key, entry)=>typeof entry === 'bigint' ? entry.toString() : entry);
+    } catch  {
+        return '[unserializable object]';
+    }
+}
+
 /**
  * Creates error for network type mismatch between source and destination.
  *
@@ -1569,7 +1597,7 @@ let activeRedactor = defaultMessageRedactor;
  * // Message: "Validation failed for 'chainId': 999 - Unsupported chain ID"
  *
  * throw createValidationFailedError('config', { invalid: true }, 'Missing required properties')
- * // Message: "Validation failed for 'config': [object Object] - Missing required properties"
+ * // Message: "Validation failed for 'config': {"invalid":true} - Missing required properties"
  * ```
  */ function createValidationFailedError$1(field, value, reason) {
     // Convert value to string for display, handling different types appropriately
@@ -1577,7 +1605,7 @@ let activeRedactor = defaultMessageRedactor;
     if (typeof value === 'string') {
         valueString = `'${value}'`;
     } else if (typeof value === 'object' && value !== null) {
-        valueString = JSON.stringify(value);
+        valueString = describeObjectValue(value);
     } else {
         valueString = String(value);
     }
@@ -2976,6 +3004,105 @@ let activeRedactor = defaultMessageRedactor;
     return chain;
 }
 
+/**
+ * Extracts the HTTP status code from an error message.
+ *
+ * Attempts to parse HTTP status codes from common error message formats,
+ * such as "HTTP 404" or "Status: 500".
+ *
+ * Shared by `parseApiError` and the backend-error-code parsers that route on
+ * status when no backend code is available, so all of them recognise the same
+ * message shapes.
+ *
+ * @param msg - The error message to extract from
+ * @returns The extracted HTTP status code, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const code = extractHttpStatusCode('HTTP 404')
+ * // Returns: 404
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const code = extractHttpStatusCode('Status: 500 Internal Server Error')
+ * // Returns: 500
+ * ```
+ *
+ * @internal
+ */ function extractHttpStatusCode(msg) {
+    // Pattern: "HTTP 404" or "HTTP 404 - some message" or "Status: 404"
+    const patterns = [
+        /HTTP (\d{3})/i,
+        /Status:\s*(\d{3})/i,
+        /^(\d{3}) -/
+    ];
+    for (const pattern of patterns){
+        const match = pattern.exec(msg);
+        const codeStr = match?.at(1);
+        if (codeStr !== undefined) {
+            const code = Number.parseInt(codeStr, 10);
+            // Validate it's a valid HTTP status code
+            if (code >= 100 && code < 600) {
+                return code;
+            }
+        }
+    }
+    return null;
+}
+
+/**
+ * Type guard that narrows an unknown error to one carrying a non-null
+ * object `responseBody` property (attached by `makeApiRequest`).
+ *
+ * Shared by backend-error-code parsers (`parseEarnApiError`,
+ * `parseBorrowApiError`) so the narrowing logic lives in one place.
+ *
+ * @param error - The raw error from the HTTP layer
+ * @returns `true` when `error.responseBody` is a non-null object
+ * @internal
+ */ function hasResponseBody(error) {
+    return typeof error === 'object' && error !== null && 'responseBody' in error && typeof error['responseBody'] === 'object' && error['responseBody'] !== null;
+}
+/**
+ * Narrow an unknown value to a non-null object.
+ *
+ * @param value - The value to check
+ * @returns `true` when `value` is a non-null object
+ * @internal
+ */ function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Read the machine-readable error fields (`code`, `message`,
+ * `externalMessage`) that a Circle service attaches to an HTTP error body.
+ *
+ * `platform-common-go` serializes app-thrown errors under a nested envelope —
+ * `{ response: { status: { code, message, externalMessage } } }` — for every
+ * HTTP status, so this returns that inner `response.status` object when
+ * present. It otherwise falls back to the top-level body so a flattened shape
+ * (e.g. the stablecoin-kits-proxy) is still read. Callers read
+ * `code` / `message` / `externalMessage` off the returned object uniformly.
+ *
+ * @param error - The raw error from the HTTP layer
+ * @returns The error-status fields, or `undefined` when the error carries no
+ *   response body
+ * @internal
+ */ function extractResponseBody$1(error) {
+    if (!hasResponseBody(error)) {
+        return undefined;
+    }
+    const body = error.responseBody;
+    const response = body['response'];
+    if (isRecord(response)) {
+        const status = response['status'];
+        if (isRecord(status)) {
+            return status;
+        }
+    }
+    return body;
+}
+
 /**
  * Proxy-specific structured error codes carried in `responseBody.code`.
  *
@@ -3276,29 +3403,22 @@ let activeRedactor = defaultMessageRedactor;
     });
 }
 /**
- * Type guard that narrows an unknown error to one carrying a non-null
- * object `responseBody` property (attached by `makeApiRequest`).
+ * Extract the machine-readable error fields that `makeApiRequest` attaches to
+ * HTTP error instances.
  *
- * @param error - The raw error from the HTTP layer
- * @returns `true` when `error.responseBody` is a non-null object
- * @internal
- */ function hasResponseBody(error) {
-    return typeof error === 'object' && error !== null && 'responseBody' in error && typeof error['responseBody'] === 'object' && error['responseBody'] !== null;
-}
-/**
- * Extract the `responseBody` property that `makeApiRequest` attaches to
- * HTTP error instances when the server returns a JSON body.
+ * Delegates to the shared extractor so this fall-through path reads the same
+ * shape as the backend-code parsers: it unwraps the nested
+ * `{ response: { status } }` envelope when present, otherwise returns the
+ * top-level body. Routing both halves through one extractor keeps an
+ * unmapped-code error from losing the server's `externalMessage`.
  *
  * @param error - The raw error from the HTTP layer
- * @returns The parsed body cast to {@link ApiErrorResponseBody}, or undefined
+ * @returns The parsed body as {@link ApiErrorResponseBody}, or undefined
  * @throws Never. Returns `undefined` when the error does not carry a valid
  *   `responseBody`.
  * @internal
  */ function extractResponseBody(error) {
-    if (!hasResponseBody(error)) {
-        return undefined;
-    }
-    return error.responseBody;
+    return extractResponseBody$1(error);
 }
 /**
  * Extract a field name from an {@link ApiFieldError}.
@@ -3407,46 +3527,6 @@ let activeRedactor = defaultMessageRedactor;
     }
     return topMessage ?? fieldDetail;
 }
-/**
- * Extracts the HTTP status code from an error message.
- *
- * Attempts to parse HTTP status codes from common error message formats,
- * such as "HTTP 404" or "Status: 500".
- *
- * @param msg - The error message to extract from
- * @returns The extracted HTTP status code, or null if not found
- *
- * @example
- * ```typescript
- * const code = extractHttpStatusCode('HTTP 404')
- * // Returns: 404
- * ```
- *
- * @example
- * ```typescript
- * const code = extractHttpStatusCode('Status: 500 Internal Server Error')
- * // Returns: 500
- * ```
- */ function extractHttpStatusCode(msg) {
-    // Pattern: "HTTP 404" or "HTTP 404 - some message" or "Status: 404"
-    const patterns = [
-        /HTTP (\d{3})/i,
-        /Status:\s*(\d{3})/i,
-        /^(\d{3}) -/
-    ];
-    for (const pattern of patterns){
-        const match = pattern.exec(msg);
-        const codeStr = match?.at(1);
-        if (codeStr !== undefined) {
-            const code = Number.parseInt(codeStr, 10);
-            // Validate it's a valid HTTP status code
-            if (code >= 100 && code < 600) {
-                return code;
-            }
-        }
-    }
-    return null;
-}
 
 /**
  * @packageDocumentation
@@ -3702,6 +3782,11 @@ var EarnChain;
     "Arc",
     "Arc_Testnet"
 ];
+var BorrowChain;
+(function(BorrowChain) {
+    BorrowChain["Arc"] = "Arc";
+    BorrowChain["Arc_Testnet"] = "Arc_Testnet";
+})(BorrowChain || (BorrowChain = {}));
 
 /**
  * Helper function to define a chain with proper TypeScript typing.
@@ -4044,6 +4129,29 @@ var EarnChain;
  * on EVM-compatible testnet chains. Use this address for testnet adapter
  * integrations (e.g., Arc Testnet).
  */ const ADAPTER_CONTRACT_EVM_TESTNET = '0xBBD70b01a1CAbc96d5b7b129Ae1AAabdf50dd40b';
+/**
+ * The sender-preserving batching contract on Arc (`Multicall3From`).
+ *
+ * This predeploy batches calls like the ubiquitous Multicall3, but routes each
+ * subcall through Arc's `CallFrom` precompile
+ * (`0x1800000000000000000000000000000000000003`), which executes on behalf of
+ * the transaction's original sender. Every target therefore sees the calling
+ * EOA as `msg.sender`, which is what makes a plain, un-upgraded EOA capable of
+ * an atomic batch on Arc.
+ *
+ * Deployed at the same address on Arc Testnet and Arc Mainnet.
+ *
+ * @see https://docs.arc.io/arc/concepts/batched-transactions
+ */ const BATCHER_CONTRACT_ARC_TESTNET = '0x522fAf9A91c41c443c66765030741e4AaCe147D0';
+/**
+ * The sender-preserving batching contract on Arc Mainnet (`Multicall3From`).
+ *
+ * See {@link BATCHER_CONTRACT_ARC_TESTNET} for how this contract works.
+ * Requires Arc's Zero7 hardfork, which activates the `CallFrom` precompile
+ * this contract depends on.
+ *
+ * @see https://docs.arc.io/arc/concepts/batched-transactions
+ */ const BATCHER_CONTRACT_ARC_MAINNET = '0x522fAf9A91c41c443c66765030741e4AaCe147D0';
 /**
  * The GatewayWallet contract address for EVM mainnet networks.
  *
@@ -4193,7 +4301,10 @@ var EarnChain;
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
-        adapter: ADAPTER_CONTRACT_EVM_MAINNET
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
+        // Arc is the only chain with a sender-preserving batcher, because it
+        // takes a precompile rather than an ordinary contract to build one.
+        senderPreservingBatcher: BATCHER_CONTRACT_ARC_MAINNET
     },
     gateway: {
         domain: 26,
@@ -4264,7 +4375,10 @@ var EarnChain;
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
-        adapter: ADAPTER_CONTRACT_EVM_TESTNET
+        adapter: ADAPTER_CONTRACT_EVM_TESTNET,
+        // Arc is the only chain with a sender-preserving batcher, because it
+        // takes a precompile rather than an ordinary contract to build one.
+        senderPreservingBatcher: BATCHER_CONTRACT_ARC_TESTNET
     },
     gateway: {
         domain: 26,
@@ -7939,7 +8053,8 @@ var Chains = {
     cctpx: zod.z.any().optional(),
     kitContracts: zod.z.object({
         bridge: zod.z.string().optional(),
-        adapter: zod.z.string().optional()
+        adapter: zod.z.string().optional(),
+        senderPreservingBatcher: zod.z.string().optional()
     }).optional(),
     gateway: gatewayConfigSchema.optional()
 });
@@ -8135,6 +8250,38 @@ var Chains = {
             message: `"${chain.chain}" is not a supported earn chain. ` + `Supported chains: ${Object.values(EarnChain).join(', ')}`
         }))
 ]);
+/**
+ * Zod schema for validating Borrow-specific chain identifiers.
+ *
+ * Validate that the provided chain is supported for Borrow Kit's loan
+ * operations. Unlike {@link earnChainIdentifierSchema}, this includes Arc
+ * mainnet as well as Arc Testnet.
+ *
+ * Accept a BorrowChain enum value, a matching string literal, or a
+ * ChainDefinition for a supported chain.
+ *
+ * @example
+ * ```typescript
+ * import { borrowChainIdentifierSchema } from '@core/chains'
+ * import { Arc, BorrowChain } from '@core/chains'
+ *
+ * // Valid
+ * borrowChainIdentifierSchema.parse(BorrowChain.Arc)
+ * borrowChainIdentifierSchema.parse('Arc')
+ * borrowChainIdentifierSchema.parse(Arc)
+ *
+ * // Invalid (throws ZodError)
+ * borrowChainIdentifierSchema.parse('Solana')
+ * ```
+ */ zod.z.union([
+    zod.z.string().refine((val)=>val in BorrowChain, (val)=>({
+            message: `"${val}" is not a supported borrow chain. ` + `Supported chains: ${Object.values(BorrowChain).join(', ')}`
+        })),
+    zod.z.nativeEnum(BorrowChain),
+    chainDefinitionSchema$2.refine((chain)=>chain.chain in BorrowChain, (chain)=>({
+            message: `"${chain.chain}" is not a supported borrow chain. ` + `Supported chains: ${Object.values(BorrowChain).join(', ')}`
+        }))
+]);
 // Widened views so `.includes()` accepts arbitrary strings under strict TS.
 const EARN_BRIDGE_SOURCE_CHAIN_VALUES = EARN_BRIDGE_SOURCE_BLOCKCHAINS;
 const EARN_BRIDGE_DESTINATION_CHAIN_VALUES = EARN_BRIDGE_DESTINATION_BLOCKCHAINS;
@@ -8389,8 +8536,13 @@ const swapTokenEnumSchema = zod.z.enum([
  */ function resolveChainName(value) {
     if (value == null) return undefined;
     if (typeof value === 'string') return value;
-    if (typeof value === 'object' && 'chain' in value && typeof value.chain === 'string') {
-        return value.chain;
+    try {
+        if (typeof value === 'object' && 'chain' in value) {
+            const chain = value.chain;
+            if (typeof chain === 'string') return chain;
+        }
+    } catch  {
+        return undefined;
     }
     return undefined;
 }
@@ -8999,6 +9151,7 @@ const swapTokenEnumSchema = zod.z.enum([
  * - Retries on rate limiting (429)
  * - Does not retry on client errors (4xx, except 429)
  * - Does not retry on validation failures
+ * - Does not retry when `config.isTerminalError` marks the error terminal
  *
  * Each HTTP request is given a configurable timeout before it is aborted.
  * Between retry attempts the wait depends on the `backoff` strategy. The
@@ -9078,7 +9231,10 @@ const swapTokenEnumSchema = zod.z.enum([
             return await makeApiRequest(url, method, isValidType, effectiveConfig, body);
         } catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
-            if (!isRetryableError(error)) {
+            // A caller-supplied predicate can mark an error terminal (e.g. a
+            // deterministic 404) so it is surfaced immediately instead of burning
+            // the retry budget on a non-transient answer.
+            if (effectiveConfig.isTerminalError?.(error) === true || !isRetryableError(error)) {
                 throw error;
             }
             lastError = error;
@@ -9162,7 +9318,24 @@ const swapTokenEnumSchema = zod.z.enum([
  * // After this call, TypeScript knows params is of type BridgeParams
  * ```
  */ function validate(value, schema, context) {
-    const result = schema.safeParse(value);
+    let result;
+    try {
+        result = schema.safeParse(value);
+    } catch (error) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Invalid ${context}: reading a property threw`,
+            cause: {
+                trace: {
+                    validationErrors: [
+                        'Reading a property of the value threw'
+                    ],
+                    originalError: error
+                }
+            }
+        });
+    }
     if (!result.success) {
         throw createValidationErrorFromZod(result.error, context);
     }
@@ -11724,7 +11897,7 @@ function resolveOptions(options) {
 }
 
 var name = "@circle-fin/unified-balance-kit";
-var version$1 = "1.7.0";
+var version$1 = "1.8.0";
 var pkg$1 = {
 	name: name,
 	version: version$1};
@@ -12433,6 +12606,12 @@ const READ_ACTION_KEY_SET = new Set(READ_ACTION_KEYS);
     /** EIP-2612 standard permit */ PermitType[PermitType["EIP2612"] = 1] = "EIP2612";
 })(PermitType || (PermitType = {}));
 
+var BorrowPermitType;
+(function(BorrowPermitType) {
+    /** Tokens must be approved separately. */ BorrowPermitType[BorrowPermitType["NONE"] = 0] = "NONE";
+    /** EIP-2612 permit calldata accompanies the token input. */ BorrowPermitType[BorrowPermitType["EIP2612"] = 1] = "EIP2612";
+})(BorrowPermitType || (BorrowPermitType = {}));
+
 /**
  * Default clock implementation.
  *
@@ -17200,7 +17379,7 @@ const abiParameterSchema = zod.z.object({
  * const result = evmPreparedChainRequestParamsSchema.safeParse(params)
  * ```
  */ zod.z.object({
-    type: zod.z.literal('evm'),
+    type: zod.z.literal('evm').optional(),
     abi: abiSchema,
     address: evmAddressSchema$1,
     functionName: zod.z.string({
@@ -18501,7 +18680,7 @@ function groupKey(alloc) {
     }
 }
 
-const hexBytesSchema = zod.z.string().regex(/^0x([0-9a-fA-F]{2})*$/, {
+const hexBytesSchema$1 = zod.z.string().regex(/^0x([0-9a-fA-F]{2})*$/, {
     message: 'value must be a 0x-prefixed even-length hex string'
 }).transform((value)=>value);
 zod.z.object({
@@ -18513,6 +18692,53 @@ zod.z.object({
         amount: zod.z.bigint().refine((value)=>value >= 0n, {
             message: 'amount must be a non-negative bigint'
         }),
+        permitCalldata: hexBytesSchema$1
+    }))
+}).passthrough();
+
+const hexBytesSchema = zod.z.string().regex(/^0x([0-9a-fA-F]{2})*$/, {
+    message: 'value must be a 0x-prefixed even-length hex string'
+}).transform((value)=>value);
+function isNonNegativeBigIntLike(value) {
+    try {
+        return BigInt(value) >= 0n;
+    } catch  {
+        return false;
+    }
+}
+const uint256LikeSchema = zod.z.union([
+    zod.z.string(),
+    zod.z.bigint()
+]).refine(isNonNegativeBigIntLike, {
+    message: 'value must be a non-negative bigint-compatible string or bigint'
+});
+const borrowExecutionParamsSchema = zod.z.object({
+    instructions: zod.z.array(zod.z.object({
+        target: evmAddressSchema$1,
+        data: hexBytesSchema,
+        value: uint256LikeSchema,
+        tokenIn: evmAddressSchema$1,
+        amountToApprove: uint256LikeSchema,
+        tokenOut: evmAddressSchema$1,
+        minTokenOut: uint256LikeSchema
+    }).passthrough()).min(1),
+    tokens: zod.z.array(zod.z.object({
+        token: evmAddressSchema$1,
+        beneficiary: evmAddressSchema$1
+    }).passthrough()),
+    execId: uint256LikeSchema,
+    deadline: uint256LikeSchema,
+    metadata: hexBytesSchema
+}).passthrough();
+zod.z.object({
+    executeParams: borrowExecutionParamsSchema,
+    signature: evmSignatureSchema,
+    tokenInputs: zod.z.array(zod.z.object({
+        permitType: zod.z.nativeEnum(BorrowPermitType),
+        token: evmAddressSchema$1,
+        amount: zod.z.bigint().refine((value)=>value >= 0n, {
+            message: 'amount must be a non-negative bigint'
+        }),
         permitCalldata: hexBytesSchema
     }))
 }).passthrough();
@@ -29018,7 +29244,7 @@ const mockAttestationMessage = {
     return step;
 }
 
-var version = "1.14.0";
+var version = "1.14.1";
 var pkg = {
 	version: version};
 
@@ -31354,9 +31580,9 @@ const allowanceStrategySchema = zod.z.enum([
 /**
  * Schema for validating estimateDeposit parameters.
  *
- * Validates `from` (adapter + chain), `amount`, required `to.chain`,
- * optional `token`, `config.transferSpeed`, `depositAccount`, and
- * `allowanceStrategy`.
+ * Validates `from` (adapter + chain), `amount`, optional `to.chain`
+ * (defaults to Arc / Arc_Testnet for FAST), optional `token`,
+ * `config.transferSpeed`, `depositAccount`, and `allowanceStrategy`.
  *
  * @example
  * ```typescript
@@ -31457,12 +31683,12 @@ const allowanceStrategySchema = zod.z.enum([
  */ function validateDepositTransferConfig(params) {
     const { from, to, config, quote, allowanceStrategy } = params;
     const transferSpeed = config?.transferSpeed ?? 'STANDARD';
-    if (to !== undefined && allowanceStrategy !== undefined) {
-        throw createValidationFailedError$1('allowanceStrategy', allowanceStrategy, 'cannot be set when to is provided; FAST deposits do not use an ' + 'allowance strategy');
+    if (transferSpeed === 'FAST' && allowanceStrategy !== undefined) {
+        throw createValidationFailedError$1('allowanceStrategy', allowanceStrategy, 'cannot be set for FAST cross-chain deposits');
     }
     if (transferSpeed === 'FAST') {
         if (to === undefined) {
-            throw createValidationFailedError$1('to', undefined, 'required when transferSpeed is FAST');
+            throw createValidationFailedError$1('to', undefined, 'required when transferSpeed is FAST and no default destination ' + 'can be derived from from.chain');
         }
         const dstChain = resolveChainIdentifier(to.chain);
         if (!isGatewayFastDepositDestination(dstChain)) {
@@ -31521,8 +31747,9 @@ const allowanceStrategySchema = zod.z.enum([
 }
 /**
  * Run all validations required for estimateDeposit: from context, amount,
- * required `to.chain`, optional token, config, depositAccount, and
- * allowanceStrategy.
+ * optional `to.chain`, optional token, config, depositAccount, and
+ * allowanceStrategy. FAST params must already have the default destination
+ * applied (see `applyDefaultFastDepositDestination`).
  *
  * @param params - The raw estimateDeposit params.
  * @returns Nothing; throws on invalid params.
@@ -31595,6 +31822,90 @@ const allowanceStrategySchema = zod.z.enum([
     }
 }
 
+/**
+ * Default destination chain for FAST cross-chain deposits, keyed by the
+ * network of the source chain. Used when `config.transferSpeed` is `'FAST'`
+ * and `to` is omitted.
+ */ const DEFAULT_FAST_DEPOSIT_DESTINATION = {
+    mainnet: Blockchain.Arc,
+    testnet: Blockchain.Arc_Testnet
+};
+/**
+ * Resolve the destination chain for a deposit.
+ *
+ * Return `to` unchanged when it is set or when the transfer speed is not
+ * `'FAST'`. Otherwise return the default FAST deposit destination for the
+ * source chain's network — `Arc` for mainnet sources and `Arc_Testnet` for
+ * testnet sources.
+ *
+ * @param params - Deposit params with `from`, optional `to`, and optional
+ *   `config`. `from.chain` must already be validated.
+ * @returns The explicit or defaulted destination, or `undefined` for
+ *   STANDARD deposits.
+ * @throws KitError If `from.chain` cannot be resolved.
+ *
+ * @example
+ * ```typescript
+ * const to = resolveFastDepositDestination({
+ *   from: { chain: 'Ethereum_Sepolia' },
+ *   config: { transferSpeed: 'FAST' },
+ * })
+ * // to → { chain: 'Arc_Testnet' }
+ * ```
+ */ function resolveFastDepositDestination(params) {
+    const { from, to, config } = params;
+    if (to !== undefined || config?.transferSpeed !== 'FAST') {
+        return to;
+    }
+    const srcChain = resolveChainIdentifier(from.chain);
+    return {
+        chain: srcChain.isTestnet ? DEFAULT_FAST_DEPOSIT_DESTINATION.testnet : DEFAULT_FAST_DEPOSIT_DESTINATION.mainnet
+    };
+}
+/**
+ * Return deposit params with the default FAST deposit destination applied.
+ *
+ * Call this at the top of every deposit entry point, before validation, so
+ * all downstream logic (validation, routing, telemetry, and the estimate
+ * result) sees an explicit `to` for every FAST deposit.
+ *
+ * When {@link resolveFastDepositDestination} yields a destination and `to`
+ * is not set, return a shallow copy with `to` filled in. Otherwise return
+ * the params unchanged. Safe to call more than once.
+ *
+ * Runs before validation, so it never throws: when `from.chain` cannot be
+ * resolved (or `params` is malformed plain-JS input) the params are returned
+ * unchanged and schema validation reports the error.
+ *
+ * @typeParam T - The deposit, depositFor, or estimateDeposit params type.
+ * @param params - Raw (unvalidated) deposit params.
+ * @returns Params with `to` set for every resolvable FAST deposit.
+ *
+ * @example
+ * ```typescript
+ * const resolved = applyDefaultFastDepositDestination({
+ *   from: { adapter, chain: 'Base' },
+ *   amount: '10',
+ *   config: { transferSpeed: 'FAST' },
+ * })
+ * // resolved.to → { chain: 'Arc' }
+ * ```
+ */ function applyDefaultFastDepositDestination(params) {
+    let to;
+    try {
+        to = resolveFastDepositDestination(params);
+    } catch  {
+        // Unresolvable source chain — leave params as-is for validation to reject.
+        return params;
+    }
+    if (to === undefined || to === params.to) {
+        return params;
+    }
+    return {
+        ...params,
+        to
+    };
+}
 async function resolveDepositParams(params) {
     const chain = resolveChainIdentifier(params.from.chain);
     params.from.adapter.validateChainSupport(chain);
@@ -31853,7 +32164,9 @@ function resolveGatewayExecutorContracts(srcChain, dstChain) {
  * covers the amount) → burn → relay wait.
  *
  * @param context - Kit context (used for analytics telemetry emissions).
- * @param params - Deposit params (must have `to` set and `to.chain` differ from `from.chain`).
+ * @param params - Deposit params with `to` set (explicitly or via
+ *   `applyDefaultFastDepositDestination`) and `to.chain` differing from
+ *   `from.chain`.
  * @param depositAccount - Destination Gateway account to credit. When omitted
  *   (i.e. called from `deposit()`), the signer's own address is used.
  * @returns Settled deposit result after Circle's relay has confirmed the mint.
@@ -32114,7 +32427,8 @@ function resolveGatewayExecutorContracts(srcChain, dstChain) {
  * (token → `'USDC'`, allowanceStrategy → `'authorize'`), finds a provider,
  * and delegates to the provider's deposit operation.
  *
- * For cross-chain (FAST) deposits (when `to` is set): fetches or validates a
+ * For cross-chain (FAST) deposits (when `config.transferSpeed` is `'FAST'`;
+ * `to` defaults to Arc / Arc_Testnet when omitted): fetches or validates a
  * fee quote, runs a preflight affordability check, submits the prepaid-FORWARD
  * burn on the source chain, and waits for Circle's relay to confirm the mint
  * on the destination. The caller's Gateway account is credited on the
@@ -32153,11 +32467,12 @@ function resolveGatewayExecutorContracts(srcChain, dstChain) {
  * const crossResult = await deposit(context, { ...estimate, from: { adapter, chain: 'Ethereum_Sepolia' } })
  * ```
  */ async function deposit(context, params) {
-    assertDepositParams(params);
-    if (params.to !== undefined) {
-        return depositFastCrossChain(context, params);
+    const normalizedParams = applyDefaultFastDepositDestination(params);
+    assertDepositParams(normalizedParams);
+    if (normalizedParams.to !== undefined) {
+        return depositFastCrossChain(context, normalizedParams);
     }
-    const resolvedParams = await resolveDepositParams(params);
+    const resolvedParams = await resolveDepositParams(normalizedParams);
     const chain = resolvedParams.from.chain;
     if (!isGatewayV1Supported(chain)) {
         throw createUnsupportedRouteError(chain.name, chain.name);
@@ -32172,7 +32487,8 @@ function resolveGatewayExecutorContracts(srcChain, dstChain) {
  * (token → `'USDC'`, allowanceStrategy → `'approve'`), finds a provider,
  * and delegates to the provider's depositFor operation.
  *
- * For cross-chain (FAST) deposits (when `to` is set): fetches or validates a
+ * For cross-chain (FAST) deposits (when `config.transferSpeed` is `'FAST'`;
+ * `to` defaults to Arc / Arc_Testnet when omitted): fetches or validates a
  * fee quote, runs a preflight affordability check, submits the prepaid-FORWARD
  * burn on the source chain, and waits for Circle's relay to confirm the mint.
  * The `depositAccount` is credited on the destination chain.
@@ -32216,11 +32532,12 @@ function resolveGatewayExecutorContracts(srcChain, dstChain) {
  * })
  * ```
  */ async function depositFor(context, params) {
-    assertDepositForParams(params);
-    if (params.to !== undefined) {
-        return depositFastCrossChain(context, params, params.depositAccount);
+    const normalizedParams = applyDefaultFastDepositDestination(params);
+    assertDepositForParams(normalizedParams);
+    if (normalizedParams.to !== undefined) {
+        return depositFastCrossChain(context, normalizedParams, normalizedParams.depositAccount);
     }
-    const resolvedParams = await resolveDepositParams(params);
+    const resolvedParams = await resolveDepositParams(normalizedParams);
     const chain = resolvedParams.from.chain;
     if (!isGatewayV1Supported(chain)) {
         throw createUnsupportedRouteError(chain.name, chain.name);
@@ -32279,7 +32596,8 @@ async function estimateDepositImpl(context, params) {
             fee: depositTotalGasFee
         }, srcChain));
     } else {
-        // assertEstimateDepositParams guarantees params.to is set on the FAST path
+        // applyDefaultFastDepositDestination + assertEstimateDepositParams
+        // guarantee params.to is set on the FAST path
         const { to } = params;
         if (to === undefined) {
             /* v8 ignore next 6 -- assertEstimateDepositParams guarantees to is set on the FAST path */ throw createValidationFailedError$1('to', undefined, 'required for FAST transfers');
@@ -32430,7 +32748,8 @@ async function estimateDepositImpl(context, params) {
  *
  * @param context - Kit context (used for analytics telemetry emissions).
  * @param params - The estimate parameters: source context, amount, destination
- *   chain, optional token, transfer speed, and allowance strategy.
+ *   chain (defaults to Arc / Arc_Testnet for FAST), optional token, transfer
+ *   speed, and allowance strategy.
  * @returns Promise resolving to an itemized fee estimate with an optional
  *   quote for FAST cross-chain transfers.
  * @throws KitError If the wallet address cannot be resolved — wallet not connected
@@ -32463,8 +32782,9 @@ async function estimateDepositImpl(context, params) {
  * const result = await deposit(context, { ...estimate, from: { adapter, chain: 'Ethereum_Sepolia' } })
  * ```
  */ async function estimateDeposit(context, params) {
-    assertEstimateDepositParams(params);
-    return estimateDepositImpl(context, params);
+    const normalizedParams = applyDefaultFastDepositDestination(params);
+    assertEstimateDepositParams(normalizedParams);
+    return estimateDepositImpl(context, normalizedParams);
 }
 
 // The `as never` cast is required because `unifiedBalanceChainIdentifierSchema`
@@ -34038,6 +34358,10 @@ const removeFundParamsSchema = zod.z.object({
  * All three telemetry call sites use this helper to keep the classification
  * consistent.
  *
+ * Callers must pass params that have been through
+ * `applyDefaultFastDepositDestination`, which sets `to` to Arc / Arc_Testnet
+ * for FAST deposits that omit it.
+ *
  * @param params - Deposit or estimate-deposit params to inspect.
  * @returns `true` when the transfer is a FAST cross-chain deposit.
  */ function isFastDeposit(params) {
@@ -34177,21 +34501,22 @@ const removeFundParamsSchema = zod.z.object({
    *
    * @see UnifiedBalanceKit.depositFor to deposit into another account.
    */ async deposit(params) {
-        if (isFastDeposit(params)) {
-            return withErrorTelemetry(async ()=>deposit(this.context, params), EVENT_TYPES.FAST_DEPOSIT, this.telemetryConfig, {
-                sourceChain: resolveChainName(params.from?.chain),
-                destinationChain: resolveChainName(params.to?.chain),
-                tokenIn: params.token ?? 'USDC',
-                amountIn: Number.parseFloat(params.amount),
-                ...params.quote !== undefined && {
-                    correlationId: hashSignedQuote(params.quote)
+        const normalizedParams = applyDefaultFastDepositDestination(params);
+        if (isFastDeposit(normalizedParams)) {
+            return withErrorTelemetry(async ()=>deposit(this.context, normalizedParams), EVENT_TYPES.FAST_DEPOSIT, this.telemetryConfig, {
+                sourceChain: resolveChainName(normalizedParams.from?.chain),
+                destinationChain: resolveChainName(normalizedParams.to?.chain),
+                tokenIn: normalizedParams.token ?? 'USDC',
+                amountIn: Number.parseFloat(normalizedParams.amount),
+                ...normalizedParams.quote !== undefined && {
+                    correlationId: hashSignedQuote(normalizedParams.quote)
                 }
             });
         }
-        return withErrorTelemetry(async ()=>deposit(this.context, params), EVENT_TYPES.DEPOSIT, this.telemetryConfig, {
-            sourceChain: resolveChainName(params.from?.chain),
-            tokenIn: params.token ?? 'USDC',
-            amountIn: Number.parseFloat(params.amount)
+        return withErrorTelemetry(async ()=>deposit(this.context, normalizedParams), EVENT_TYPES.DEPOSIT, this.telemetryConfig, {
+            sourceChain: resolveChainName(normalizedParams.from?.chain),
+            tokenIn: normalizedParams.token ?? 'USDC',
+            amountIn: Number.parseFloat(normalizedParams.amount)
         });
     }
     /**
@@ -34203,24 +34528,25 @@ const removeFundParamsSchema = zod.z.object({
    *
    * @see UnifiedBalanceKit.deposit to deposit into your own account.
    */ async depositFor(params) {
-        if (isFastDeposit(params)) {
+        const normalizedParams = applyDefaultFastDepositDestination(params);
+        if (isFastDeposit(normalizedParams)) {
             // Fast depositFor shares FAST_DEPOSIT event type with fast deposit — the
             // success-path emitter in depositFastCrossChain uses a single event type
             // for both entry points, so error telemetry mirrors that here.
-            return withErrorTelemetry(async ()=>depositFor(this.context, params), EVENT_TYPES.FAST_DEPOSIT, this.telemetryConfig, {
-                sourceChain: resolveChainName(params.from?.chain),
-                destinationChain: resolveChainName(params.to?.chain),
-                tokenIn: params.token ?? 'USDC',
-                amountIn: Number.parseFloat(params.amount),
-                ...params.quote !== undefined && {
-                    correlationId: hashSignedQuote(params.quote)
+            return withErrorTelemetry(async ()=>depositFor(this.context, normalizedParams), EVENT_TYPES.FAST_DEPOSIT, this.telemetryConfig, {
+                sourceChain: resolveChainName(normalizedParams.from?.chain),
+                destinationChain: resolveChainName(normalizedParams.to?.chain),
+                tokenIn: normalizedParams.token ?? 'USDC',
+                amountIn: Number.parseFloat(normalizedParams.amount),
+                ...normalizedParams.quote !== undefined && {
+                    correlationId: hashSignedQuote(normalizedParams.quote)
                 }
             });
         }
-        return withErrorTelemetry(async ()=>depositFor(this.context, params), EVENT_TYPES.DEPOSIT_FOR, this.telemetryConfig, {
-            sourceChain: resolveChainName(params.from?.chain),
-            tokenIn: params.token ?? 'USDC',
-            amountIn: Number.parseFloat(params.amount)
+        return withErrorTelemetry(async ()=>depositFor(this.context, normalizedParams), EVENT_TYPES.DEPOSIT_FOR, this.telemetryConfig, {
+            sourceChain: resolveChainName(normalizedParams.from?.chain),
+            tokenIn: normalizedParams.token ?? 'USDC',
+            amountIn: Number.parseFloat(normalizedParams.amount)
         });
     }
     /**
@@ -34235,23 +34561,25 @@ const removeFundParamsSchema = zod.z.object({
    * ```
    *
    * @param params - The estimate parameters including source context, amount,
-   *   destination chain, optional transfer speed, and optional allowance strategy.
+   *   destination chain (defaults to Arc / Arc_Testnet for FAST), optional
+   *   transfer speed, and optional allowance strategy.
    * @returns Promise resolving to an itemised fee breakdown.
    *
    * @see UnifiedBalanceKit.deposit to execute after estimating.
    */ async estimateDeposit(params) {
-        if (isFastDeposit(params)) {
-            return withErrorTelemetry(async ()=>estimateDeposit(this.context, params), EVENT_TYPES.ESTIMATE_FAST_DEPOSIT, this.telemetryConfig, {
-                sourceChain: resolveChainName(params.from?.chain),
-                destinationChain: resolveChainName(params.to?.chain),
-                tokenIn: params.token ?? 'USDC',
-                amountIn: Number.parseFloat(params.amount)
+        const normalizedParams = applyDefaultFastDepositDestination(params);
+        if (isFastDeposit(normalizedParams)) {
+            return withErrorTelemetry(async ()=>estimateDeposit(this.context, normalizedParams), EVENT_TYPES.ESTIMATE_FAST_DEPOSIT, this.telemetryConfig, {
+                sourceChain: resolveChainName(normalizedParams.from?.chain),
+                destinationChain: resolveChainName(normalizedParams.to?.chain),
+                tokenIn: normalizedParams.token ?? 'USDC',
+                amountIn: Number.parseFloat(normalizedParams.amount)
             });
         }
-        return withErrorTelemetry(async ()=>estimateDeposit(this.context, params), EVENT_TYPES.ESTIMATE_DEPOSIT, this.telemetryConfig, {
-            sourceChain: resolveChainName(params.from?.chain),
-            tokenIn: params.token ?? 'USDC',
-            amountIn: Number.parseFloat(params.amount)
+        return withErrorTelemetry(async ()=>estimateDeposit(this.context, normalizedParams), EVENT_TYPES.ESTIMATE_DEPOSIT, this.telemetryConfig, {
+            sourceChain: resolveChainName(normalizedParams.from?.chain),
+            tokenIn: normalizedParams.token ?? 'USDC',
+            amountIn: Number.parseFloat(normalizedParams.amount)
         });
     }
     /**
@@ -34620,7 +34948,8 @@ registerKit(`${pkg$1.name}/${pkg$1.version}`);
    * {@link AppKitUnifiedBalance.depositFor}.
    *
    * @param params - Estimate details including the depositor context, amount,
-   *   destination chain, and optional transfer speed.
+   *   destination chain (defaults to Arc / Arc_Testnet for FAST), and optional
+   *   transfer speed.
    * @returns Promise resolving to the itemised fee estimate.
    * @throws {KitError} If the estimate parameters are invalid or the route is
    *   unsupported.