@circle-fin/app-kit 1.15.3 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circle-fin/app-kit",
-  "version": "1.15.3",
+  "version": "1.16.0",
   "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,12 +36,13 @@
   "module": "./index.mjs",
   "types": "./index.d.cts",
   "dependencies": {
-    "@circle-fin/onramp-kit": "1.0.2",
-    "@circle-fin/unified-balance-kit": "1.7.0",
-    "@circle-fin/provider-gateway-v1": "1.5.0",
-    "@circle-fin/earn-kit": "1.8.0",
-    "@circle-fin/bridge-kit": "1.15.1",
-    "@circle-fin/swap-kit": "1.7.0",
+    "@circle-fin/onramp-kit": "1.0.3",
+    "@circle-fin/unified-balance-kit": "1.8.0",
+    "@circle-fin/provider-gateway-v1": "1.5.1",
+    "@circle-fin/earn-kit": "1.8.1",
+    "@circle-fin/borrow-kit": "1.0.0",
+    "@circle-fin/bridge-kit": "1.15.2",
+    "@circle-fin/swap-kit": "1.7.1",
     "@coral-xyz/anchor": "^0.31.1",
     "@noble/curves": "1.4.2",
     "bn.js": "^5.2.3",
@@ -117,6 +118,14 @@
       "import": "./earn.mjs",
       "require": "./earn.cjs"
     },
+    "./borrow": {
+      "types": {
+        "import": "./borrow.d.mts",
+        "require": "./borrow.d.cts"
+      },
+      "import": "./borrow.mjs",
+      "require": "./borrow.cjs"
+    },
     "./estimateSwap": {
       "types": {
         "import": "./estimateSwap.d.mts",
@@ -152,6 +161,7 @@
     "estimateSwap.*",
     "unifiedBalance.*",
     "earn.*",
+    "borrow.*",
     "index.*",
     "server.*",
     "README.md",

package/server.cjs

@@ -639,6 +639,34 @@ class KitError extends 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 general validation failure.
  *
@@ -661,7 +689,7 @@ class KitError extends Error {
  * // 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(field, value, reason) {
     // Convert value to string for display, handling different types appropriately
@@ -669,7 +697,7 @@ class KitError extends Error {
     if (typeof value === 'string') {
         valueString = `'${value}'`;
     } else if (typeof value === 'object' && value !== null) {
-        valueString = JSON.stringify(value);
+        valueString = describeObjectValue(value);
     } else {
         valueString = String(value);
     }
@@ -1321,6 +1349,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.
@@ -1663,6 +1696,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.
  *
@@ -1802,7 +1858,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,
@@ -1873,7 +1932,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,
@@ -5291,7 +5353,8 @@ var EarnChain;
     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()
 });
@@ -5487,6 +5550,38 @@ var EarnChain;
             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.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;
@@ -8650,7 +8745,7 @@ const swapTokenEnumSchema = zod.z.enum([
     return kit;
 }
 
-var version = "1.0.2";
+var version = "1.0.3";
 var pkg = {
 	version: version};
 

package/server.mjs

@@ -633,6 +633,34 @@ class KitError extends 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 general validation failure.
  *
@@ -655,7 +683,7 @@ class KitError extends Error {
  * // 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(field, value, reason) {
     // Convert value to string for display, handling different types appropriately
@@ -663,7 +691,7 @@ class KitError extends Error {
     if (typeof value === 'string') {
         valueString = `'${value}'`;
     } else if (typeof value === 'object' && value !== null) {
-        valueString = JSON.stringify(value);
+        valueString = describeObjectValue(value);
     } else {
         valueString = String(value);
     }
@@ -1315,6 +1343,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.
@@ -1657,6 +1690,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.
  *
@@ -1796,7 +1852,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,
@@ -1867,7 +1926,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,
@@ -5285,7 +5347,8 @@ var EarnChain;
     cctpx: z.any().optional(),
     kitContracts: z.object({
         bridge: z.string().optional(),
-        adapter: z.string().optional()
+        adapter: z.string().optional(),
+        senderPreservingBatcher: z.string().optional()
     }).optional(),
     gateway: gatewayConfigSchema.optional()
 });
@@ -5481,6 +5544,38 @@ var EarnChain;
             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')
+ * ```
+ */ z.union([
+    z.string().refine((val)=>val in BorrowChain, (val)=>({
+            message: `"${val}" is not a supported borrow chain. ` + `Supported chains: ${Object.values(BorrowChain).join(', ')}`
+        })),
+    z.nativeEnum(BorrowChain),
+    chainDefinitionSchema.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;
@@ -8644,7 +8739,7 @@ const swapTokenEnumSchema = z.enum([
     return kit;
 }
 
-var version = "1.0.2";
+var version = "1.0.3";
 var pkg = {
 	version: version};