@circle-fin/usdckit 0.21.1 → 0.23.0

package/dist/cjs/providers/solana/utils/toBase64EncodedWireTransaction.js

@@ -0,0 +1,42 @@
+"use strict";
+// Copyright (c) 2025, Circle Internet Group, Inc.
+// All rights reserved.
+//
+// Circle Internet Group, Inc. CONFIDENTIAL
+//
+// This file includes unpublished proprietary source code of Circle Internet
+// Group, Inc. The copyright notice above does not
+// evidence any actual or intended publication of such source code. Disclosure
+// of this source code or any related proprietary information is strictly
+// prohibited without the express written permission of Circle Internet Group, Inc.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBase64EncodedWireTransaction = toBase64EncodedWireTransaction;
+/**
+ * Converts various transaction formats to a Base64-encoded wire transaction.
+ *
+ * This utility function handles the conversion of different transaction input types
+ * (Buffer, string, or already encoded Base64EncodedWireTransaction) into a consistent
+ * Base64EncodedWireTransaction format that can be used with Solana RPC methods.
+ *
+ * @param tx - The transaction to convert. Can be:
+ *   - Buffer: Raw transaction bytes that will be converted to base64
+ *   - string: Already base64-encoded transaction string
+ *   - Base64EncodedWireTransaction: Already properly typed, returned as-is
+ * @returns Base64-encoded wire transaction ready for RPC submission
+ *
+ * @example
+ * ```typescript
+ * // Convert Buffer to base64
+ * const txBuffer = Buffer.from([1, 2, 3]);
+ * const base64Tx = toBase64EncodedWireTransaction(txBuffer);
+ *
+ * // Pass through already encoded string
+ * const encodedTx = "SGVsbG8gV29ybGQ=";
+ * const result = toBase64EncodedWireTransaction(encodedTx);
+ * ```
+ */
+function toBase64EncodedWireTransaction(tx) {
+    if (tx instanceof Buffer)
+        tx = tx.toString('base64');
+    return tx;
+}

package/dist/cjs/providers/solana/utils/toBase64EncodedWireTransaction.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/providers/solana/utils/toBase64EncodedWireTransaction.test.js

@@ -0,0 +1,108 @@
+"use strict";
+// Copyright (c) 2025, Circle Internet Group, Inc.
+// All rights reserved.
+//
+// Circle Internet Group, Inc. CONFIDENTIAL
+//
+// This file includes unpublished proprietary source code of Circle Internet
+// Group, Inc. The copyright notice above does not
+// evidence any actual or intended publication of such source code. Disclosure
+// of this source code or any related proprietary information is strictly
+// prohibited without the express written permission of Circle Internet Group, Inc.
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const toBase64EncodedWireTransaction_js_1 = require("./toBase64EncodedWireTransaction.js");
+vitest_1.describe.concurrent('toBase64EncodedWireTransaction', () => {
+    (0, vitest_1.it)('should convert Buffer to base64 string', () => {
+        const txBytes = new Uint8Array([72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100]); // "Hello World"
+        const buffer = Buffer.from(txBytes);
+        const expected = 'SGVsbG8gV29ybGQ=';
+        const result = (0, toBase64EncodedWireTransaction_js_1.toBase64EncodedWireTransaction)(buffer);
+        (0, vitest_1.expect)(result).toBe(expected);
+        (0, vitest_1.expect)(typeof result).toBe('string');
+    });
+    (0, vitest_1.it)('should convert Buffer with transaction-like data to base64', () => {
+        // Simulate a more realistic transaction buffer with binary data
+        const txBytes = new Uint8Array([
+            0x01, 0x00, 0x01, 0x03, 0xff, 0xfe, 0xfd, 0xfc, 0xfb, 0xfa, 0xf9, 0xf8, 0xf7, 0xf6, 0xf5, 0xf4, 0xf3, 0xf2, 0xf1,
+            0xf0, 0xef, 0xee, 0xed, 0xec,
+        ]);
+        const buffer = Buffer.from(txBytes);
+        const expected = buffer.toString('base64');
+        const result = (0, toBase64EncodedWireTransaction_js_1.toBase64EncodedWireTransaction)(buffer);
+        (0, vitest_1.expect)(result).toBe(expected);
+        (0, vitest_1.expect)(typeof result).toBe('string');
+    });
+    (0, vitest_1.it)('should pass through string input unchanged', () => {
+        const base64String = 'SGVsbG8gV29ybGQ=';
+        const result = (0, toBase64EncodedWireTransaction_js_1.toBase64EncodedWireTransaction)(base64String);
+        (0, vitest_1.expect)(result).toBe(base64String);
+        (0, vitest_1.expect)(typeof result).toBe('string');
+    });
+    (0, vitest_1.it)('should pass through already encoded transaction string', () => {
+        const encodedTx = 'AQABAxYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYW';
+        const result = (0, toBase64EncodedWireTransaction_js_1.toBase64EncodedWireTransaction)(encodedTx);
+        (0, vitest_1.expect)(result).toBe(encodedTx);
+        (0, vitest_1.expect)(typeof result).toBe('string');
+    });
+    (0, vitest_1.it)('should pass through Base64EncodedWireTransaction type unchanged', () => {
+        const encodedTx = 'SGVsbG8gV29ybGQ=';
+        const result = (0, toBase64EncodedWireTransaction_js_1.toBase64EncodedWireTransaction)(encodedTx);
+        (0, vitest_1.expect)(result).toBe(encodedTx);
+        (0, vitest_1.expect)(typeof result).toBe('string');
+    });
+    (0, vitest_1.it)('should handle empty Buffer', () => {
+        const buffer = Buffer.from([]);
+        const expected = '';
+        const result = (0, toBase64EncodedWireTransaction_js_1.toBase64EncodedWireTransaction)(buffer);
+        (0, vitest_1.expect)(result).toBe(expected);
+        (0, vitest_1.expect)(typeof result).toBe('string');
+    });
+    (0, vitest_1.it)('should handle empty string', () => {
+        const emptyString = '';
+        const result = (0, toBase64EncodedWireTransaction_js_1.toBase64EncodedWireTransaction)(emptyString);
+        (0, vitest_1.expect)(result).toBe(emptyString);
+        (0, vitest_1.expect)(typeof result).toBe('string');
+    });
+    (0, vitest_1.it)('should handle single byte Buffer', () => {
+        const buffer = Buffer.from([65]); // 'A' in ASCII
+        const expected = 'QQ==';
+        const result = (0, toBase64EncodedWireTransaction_js_1.toBase64EncodedWireTransaction)(buffer);
+        (0, vitest_1.expect)(result).toBe(expected);
+        (0, vitest_1.expect)(typeof result).toBe('string');
+    });
+    (0, vitest_1.it)('should handle large Buffer data', () => {
+        // Create a larger buffer to test with more realistic transaction sizes
+        const largeArray = new Array(1000).fill(0).map((_, i) => i % 256);
+        const buffer = Buffer.from(largeArray);
+        const expected = buffer.toString('base64');
+        const result = (0, toBase64EncodedWireTransaction_js_1.toBase64EncodedWireTransaction)(buffer);
+        (0, vitest_1.expect)(result).toBe(expected);
+        (0, vitest_1.expect)(typeof result).toBe('string');
+        (0, vitest_1.expect)(result.length).toBeGreaterThan(0);
+    });
+    (0, vitest_1.it)('should maintain type safety with Base64EncodedWireTransaction return type', () => {
+        const buffer = Buffer.from('test');
+        const stringInput = 'dGVzdA==';
+        const typedInput = 'dGVzdA==';
+        // All should return the same type
+        const result1 = (0, toBase64EncodedWireTransaction_js_1.toBase64EncodedWireTransaction)(buffer);
+        const result2 = (0, toBase64EncodedWireTransaction_js_1.toBase64EncodedWireTransaction)(stringInput);
+        const result3 = (0, toBase64EncodedWireTransaction_js_1.toBase64EncodedWireTransaction)(typedInput);
+        (0, vitest_1.expect)(typeof result1).toBe('string');
+        (0, vitest_1.expect)(typeof result2).toBe('string');
+        (0, vitest_1.expect)(typeof result3).toBe('string');
+    });
+    (0, vitest_1.it)('should produce consistent results for equivalent inputs', () => {
+        const originalData = 'Hello, Solana!';
+        const buffer = Buffer.from(originalData, 'utf8');
+        const expectedBase64 = buffer.toString('base64');
+        // Test that buffer conversion produces the same result as manual base64 encoding
+        const result = (0, toBase64EncodedWireTransaction_js_1.toBase64EncodedWireTransaction)(buffer);
+        (0, vitest_1.expect)(result).toBe(expectedBase64);
+        // Test that passing the base64 string returns the same value
+        const stringResult = (0, toBase64EncodedWireTransaction_js_1.toBase64EncodedWireTransaction)(expectedBase64);
+        (0, vitest_1.expect)(stringResult).toBe(expectedBase64);
+        (0, vitest_1.expect)(stringResult).toBe(result);
+    });
+});

package/dist/cjs/providers/uniswap/actions/exactInputSingle.d.ts

@@ -1,6 +1,6 @@
-import type { Address, Account, ControlFlowOptions, ExtendedViemClient, BaseUnits } from '../../../types.js';
+import type { Address, Account, ControlFlowOptions, BaseUnits } from '../../../types.js';
 import type { Chain } from '../index.js';
-import type { Abi, FeeValuesEIP1559 } from 'viem';
+import type { Abi, Client, FeeValuesEIP1559 } from 'viem';
 /**
  * Parameters for the {@link exactInputSingle} function.
  */
@@ -53,4 +53,4 @@ export type ExactInputSingleParams = {
  * // => '0xTransactionHash'
  * ```
  */
-export declare function exactInputSingle(client: ExtendedViemClient, params: ExactInputSingleParams & ControlFlowOptions): Promise<`0x${string}`>;
+export declare function exactInputSingle(client: Client, params: ExactInputSingleParams & ControlFlowOptions): Promise<`0x${string}`>;

package/dist/cjs/providers/uniswap/actions/exactInputSingle.js

@@ -15,6 +15,7 @@ const viem_1 = require("viem");
 const actions_1 = require("viem/actions");
 const utils_1 = require("viem/utils");
 const UnsupportedChainError_js_1 = require("../../../errors/UnsupportedChainError.js");
+const getClient_js_1 = require("../../../utils/getClient.js");
 const getContract_js_1 = require("../../../utils/getContract.js");
 const parseAccount_js_1 = require("../../../utils/parseAccount.js");
 const parseAddress_js_1 = require("../../../utils/parseAddress.js");
@@ -44,15 +45,14 @@ async function exactInputSingle(client, params) {
     // REF: https://docs.uniswap.org/contracts/v3/reference/periphery/lens/QuoterV2#quoteexactinputsingle
     const { tokenIn: _tokenIn, tokenOut: _tokenOut, amountIn, amountOutMinimum = 0n, fee = 3000, sqrtPriceLimitX96 = 0n, withApprove = true, chain: _chain = client.chain, gas, fees, account: _account, } = params;
     const chain = (0, index_js_1.extractChain)(_chain) ?? (0, raise_js_1.raise)(new UnsupportedChainError_js_1.UnsupportedChainError());
-    const publicClient = (0, viem_1.createPublicClient)({ chain, transport: (0, viem_1.http)() });
+    const _client = (0, getClient_js_1.getClient)(client, chain);
     const writeContract = (0, utils_1.getAction)(client, writeContract_js_1.writeContract, 'writeContract');
     const waitForTransactionReceipt = (0, utils_1.getAction)(client, actions_1.waitForTransactionReceipt, 'waitForTransactionReceipt');
-    // HACK: `simulateContract` does not support `chain` parameter
-    const simulateContract = (0, utils_1.getAction)(publicClient, actions_1.simulateContract, 'simulateContract');
+    const simulateContract = (0, utils_1.getAction)(_client, actions_1.simulateContract, 'simulateContract');
     const router = (0, getContract_js_1.getContract)({
         address: chain.contracts.SwapRouter02.address,
         abi: chain.contracts.SwapRouter02.abi,
-        client: publicClient,
+        client: _client,
     });
     const tokenIn = (0, parseAddress_js_1.parseAddress)(_tokenIn);
     const tokenOut = (0, parseAddress_js_1.parseAddress)(_tokenOut);

package/dist/cjs/providers/uniswap/actions/getPool.d.ts

@@ -1,5 +1,6 @@
-import type { Address, ChainContract, ExtendedViemClient } from '../../../types.js';
+import type { Address, ChainContract } from '../../../types.js';
 import type { Chain } from '../index.js';
+import type { Client } from 'viem';
 /**
  * Parameters for the {@link getPool} function.
  */
@@ -36,7 +37,7 @@ export type GetPoolParams = {
  * // }
  * ```
  */
-export declare function getPool(client: ExtendedViemClient, params: GetPoolParams): Promise<{
+export declare function getPool(client: Client, params: GetPoolParams): Promise<{
     address: `0x${string}`;
     tokenIn: Address;
     tokenOut: Address;

package/dist/cjs/providers/uniswap/actions/quoteExactInputSingle.d.ts

@@ -1,5 +1,6 @@
-import type { Address, ChainContract, ExtendedViemClient, NativeUnits, BaseUnits } from '../../../types.js';
+import type { Address, ChainContract, NativeUnits, BaseUnits } from '../../../types.js';
 import type { Chain } from '../index.js';
+import type { Client } from 'viem';
 /**
  * Parameters for the {@link quoteExactInputSingle} function.
  */
@@ -40,7 +41,7 @@ export type QuoteExactInputSingleParams = {
  * // }
  * ```
  */
-export declare function quoteExactInputSingle(client: ExtendedViemClient, params: QuoteExactInputSingleParams): Promise<{
+export declare function quoteExactInputSingle(client: Client, params: QuoteExactInputSingleParams): Promise<{
     tokenOutAmount: bigint;
     sqrtPriceX96After: bigint;
     initializedTicksCrossed: bigint;

package/dist/cjs/types.d.ts

@@ -1,20 +1,12 @@
-import type { Actions as CoreActions } from './actions/index.js';
-import type * as chains from './chains/index.js';
-import type { Actions as CircleWalletsActions } from './providers/circle-wallets/actions/index.js';
-import type { EIP1474Methods as CircleWalletsMethods } from './providers/circle-wallets/transports/index.js';
-import type { Actions as CrossChainTransferProtocolActions } from './providers/cross-chain-transfer-protocol/actions/index.js';
-import type { EIP1474Methods as CrossChainTransferMethods } from './providers/cross-chain-transfer-protocol/transports/index.js';
-import type { Actions as UniswapActions } from './providers/uniswap/actions/index.js';
-import type { Logger } from 'pino';
-import type { Account, Client, EIP1474Methods, PublicActions, Transport, WalletActions } from 'viem';
 export type { Account, Address, ChainContract, GetContractReturnType as Contract, FeeValuesEIP1559, Assign as Merge, } from 'viem';
-export type Chain = (typeof chains)[keyof typeof chains];
-export type ExtendedEIP1474Methods = [...CircleWalletsMethods, ...CrossChainTransferMethods, ...EIP1474Methods];
-export type ExtendedViemClient<transport extends Transport = Transport, chain extends Chain = Chain> = Client<transport, chain, Account, ExtendedEIP1474Methods>;
-export type CircleClient = Omit<Client, 'chain'> & {
-    logger: Logger;
-    chain: Chain;
-} & PublicActions & WalletActions & UniswapActions & CircleWalletsActions & CrossChainTransferProtocolActions & CoreActions;
+/**
+ * Utility type that returns a tuple type with the first element removed.
+ *
+ * @example
+ * type Args = [string, number, boolean];
+ * type Rest = DropFirst<Args>; // [number, boolean]
+ */
+export type DropFirst<T extends unknown[]> = T extends [unknown, ...infer R] ? R : never;
 /**
  * The primary denomination of a blockchain’s currency
  *

package/dist/cjs/types.js

@@ -1,12 +1,2 @@
 "use strict";
-// Copyright (c) 2025, Circle Internet Group, Inc.
-// All rights reserved.
-//
-// Circle Internet Group, Inc. CONFIDENTIAL
-//
-// This file includes unpublished proprietary source code of Circle Internet
-// Group, Inc. The copyright notice above does not
-// evidence any actual or intended publication of such source code. Disclosure
-// of this source code or any related proprietary information is strictly
-// prohibited without the express written permission of Circle Internet Group, Inc.
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/utils/createConfig.d.ts

@@ -0,0 +1,36 @@
+import type { Chain } from '../chains.js';
+import type { Transport } from 'viem';
+export interface TransportFactoryParams {
+    /** Required chain ID for the transport */
+    chainId: number;
+}
+/**
+ * Configuration parameters for creating a wagmi config with transport factory.
+ */
+type CreateConfigParams = {
+    /** Array of blockchain chains to support. Must contain at least one chain. */
+    chains: Chain[];
+    /** Factory function that creates a transport for a given chain ID. */
+    transportFactory: (params: TransportFactoryParams) => Transport;
+};
+/**
+ * Creates a wagmi configuration with fallback transport support for multiple chains.
+ *
+ * @param params - Configuration parameters including chains and transport factory
+ * @returns Wagmi configuration object ready for use with clients
+ * @throws Will throw an error when chains array is empty
+ *
+ * @example
+ * ```typescript
+ * const config = createConfig({
+ *   chains: [chains.ETH_SEPOLIA, chains.MATIC_AMOY],
+ *   transportFactory: ({ chainId }) => circleWalletsTransport({
+ *     apiKey: 'your-api-key',
+ *     entitySecret: 'your-entity-secret',
+ *     chainId
+ *   })
+ * })
+ * ```
+ */
+export declare function createConfig(params: CreateConfigParams): import("@wagmi/core").Config<[Chain, ...Chain[]], Record<number, Transport>, readonly import("@wagmi/core").CreateConnectorFn[]>;
+export {};

package/dist/cjs/utils/createConfig.js

@@ -0,0 +1,51 @@
+"use strict";
+// Copyright (c) 2025, Circle Internet Group, Inc.
+// All rights reserved.
+//
+// Circle Internet Group, Inc. CONFIDENTIAL
+//
+// This file includes unpublished proprietary source code of Circle Internet
+// Group, Inc. The copyright notice above does not
+// evidence any actual or intended publication of such source code. Disclosure
+// of this source code or any related proprietary information is strictly
+// prohibited without the express written permission of Circle Internet Group, Inc.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConfig = createConfig;
+const core_1 = require("@wagmi/core");
+const viem_1 = require("viem");
+const index_js_1 = require("../providers/cross-chain-transfer-protocol/index.js");
+const index_js_2 = require("../providers/solana/index.js");
+/**
+ * Creates a wagmi configuration with fallback transport support for multiple chains.
+ *
+ * @param params - Configuration parameters including chains and transport factory
+ * @returns Wagmi configuration object ready for use with clients
+ * @throws Will throw an error when chains array is empty
+ *
+ * @example
+ * ```typescript
+ * const config = createConfig({
+ *   chains: [chains.ETH_SEPOLIA, chains.MATIC_AMOY],
+ *   transportFactory: ({ chainId }) => circleWalletsTransport({
+ *     apiKey: 'your-api-key',
+ *     entitySecret: 'your-entity-secret',
+ *     chainId
+ *   })
+ * })
+ * ```
+ */
+function createConfig(params) {
+    const { chains, transportFactory } = params;
+    if (chains.length === 0) {
+        throw new Error('At least one chain must be provided');
+    }
+    const transports = chains.reduce((acc, chain) => {
+        const transportProviders = [(0, index_js_1.http)({}), (0, index_js_2.http)({}), transportFactory({ chainId: chain.id })];
+        acc[chain.id] = (0, viem_1.fallback)(transportProviders);
+        return acc;
+    }, {});
+    return (0, core_1.createConfig)({
+        chains: chains,
+        transports,
+    });
+}

package/dist/cjs/utils/createConfig.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/utils/createConfig.test.js

@@ -0,0 +1,66 @@
+"use strict";
+// Copyright (c) 2025, Circle Internet Group, Inc.
+// All rights reserved.
+//
+// Circle Internet Group, Inc. CONFIDENTIAL
+//
+// This file includes unpublished proprietary source code of Circle Internet
+// Group, Inc. The copyright notice above does not
+// evidence any actual or intended publication of such source code. Disclosure
+// of this source code or any related proprietary information is strictly
+// prohibited without the express written permission of Circle Internet Group, Inc.
+Object.defineProperty(exports, "__esModule", { value: true });
+const viem_1 = require("viem");
+const vitest_1 = require("vitest");
+const index_js_1 = require("../chains/index.js");
+const createConfig_js_1 = require("./createConfig.js");
+// Mock transport providers
+vitest_1.vi.mock('../providers/circle-wallets/index.js', () => ({
+    http: vitest_1.vi.fn(() => ({ type: 'circle-wallets' })),
+}));
+vitest_1.vi.mock('../providers/cross-chain-transfer-protocol/index.js', () => ({
+    http: vitest_1.vi.fn(() => ({ type: 'cctp' })),
+}));
+vitest_1.vi.mock('../providers/solana/index.js', () => ({
+    http: vitest_1.vi.fn(() => ({ type: 'solana' })),
+}));
+(0, vitest_1.describe)('createConfig', () => {
+    (0, vitest_1.test)('should create config with provided chains', () => {
+        const config = (0, createConfig_js_1.createConfig)({
+            chains: [index_js_1.ETH_SEPOLIA, index_js_1.MATIC_AMOY],
+            transportFactory: ({ chainId }) => (0, viem_1.http)(`https://rpc-${chainId}.example.com`),
+        });
+        (0, vitest_1.expect)(config).toBeDefined();
+        (0, vitest_1.expect)(config.chains).toEqual([index_js_1.ETH_SEPOLIA, index_js_1.MATIC_AMOY]);
+    });
+    (0, vitest_1.test)('should throw error for empty chains array', () => {
+        (0, vitest_1.expect)(() => (0, createConfig_js_1.createConfig)({
+            chains: [],
+            transportFactory: ({ chainId }) => (0, viem_1.http)(`https://rpc-${chainId}.example.com`),
+        })).toThrow('At least one chain must be provided');
+    });
+    (0, vitest_1.test)('should handle single chain', () => {
+        const config = (0, createConfig_js_1.createConfig)({
+            chains: [index_js_1.ETH_SEPOLIA],
+            transportFactory: ({ chainId }) => (0, viem_1.http)(`https://rpc-${chainId}.example.com`),
+        });
+        (0, vitest_1.expect)(config).toBeDefined();
+        (0, vitest_1.expect)(config.chains).toEqual([index_js_1.ETH_SEPOLIA]);
+    });
+    (0, vitest_1.test)('should work with Circle Wallets transport factory', () => {
+        const config = (0, createConfig_js_1.createConfig)({
+            chains: [index_js_1.ETH_SEPOLIA, index_js_1.MATIC_AMOY],
+            transportFactory: ({ chainId }) => (0, viem_1.http)(`https://circle-wallets-${chainId}.example.com`),
+        });
+        (0, vitest_1.expect)(config).toBeDefined();
+        (0, vitest_1.expect)(config.chains).toEqual([index_js_1.ETH_SEPOLIA, index_js_1.MATIC_AMOY]);
+    });
+    (0, vitest_1.test)('should work with custom transport factory', () => {
+        const config = (0, createConfig_js_1.createConfig)({
+            chains: [index_js_1.ETH_SEPOLIA],
+            transportFactory: ({ chainId }) => (0, viem_1.http)(`https://custom-rpc-${chainId}.example.com`),
+        });
+        (0, vitest_1.expect)(config).toBeDefined();
+        (0, vitest_1.expect)(config.chains).toEqual([index_js_1.ETH_SEPOLIA]);
+    });
+});

package/dist/cjs/utils/createCustomWalletClient.d.ts

@@ -0,0 +1,46 @@
+import type { Chain } from '../chains.js';
+import type { CustomWalletClient } from '../client.js';
+import type { TransportFactoryParams } from './createConfig.js';
+import type { Transport } from 'viem';
+export type CreateCustomWalletClientParams = {
+    /** Default chain for operations when no chain is specified, defaults to {@link ETH_SEPOLIA} */
+    defaultChain?: Chain;
+    /** Chains this client will work with */
+    chains?: Chain[];
+    /** Factory function that creates transport for a given chain */
+    customTransportFactory: (params: TransportFactoryParams) => Transport;
+};
+/**
+ * Creates a client with a custom wallet provider transport.
+ *
+ * @param params - The parameters for creating the client
+ * @returns A configured Circle client instance with custom wallet support
+ *
+ * @example
+ * Initialize a client with Fireblocks provider
+ * ```typescript
+ * import { createCustomWalletClient } from '@circle-fin/usdckit/utils'
+ * import { custom } from 'viem'
+ * import { FireblocksWeb3Provider } from '@fireblocks/fireblocks-web3-provider'
+ *
+ * const config = {
+ *   apiKey: process.env.FIREBLOCKS_API_KEY || '',
+ *   privateKey: process.env.FIREBLOCKS_API_PRIVATE_KEY_PATH || '',
+ *   vaultAccountIds: ['2'],
+ *   apiBaseUrl: ApiBaseUrl.Sandbox,
+ * };
+ *
+ * const client = createCustomWalletClient({
+ *   defaultChain: chains.ETH_SEPOLIA,
+ *   chains: [chains.ETH_SEPOLIA, chains.MATIC_AMOY],
+ *   customTransportFactory: ({ chainId }) =>
+ *     custom(
+ *       new FireblocksWeb3Provider({
+ *         ...config,
+ *         chainId,
+ *       }),
+ *     ),
+ * });
+ * ```
+ */
+export declare function createCustomWalletClient(params: CreateCustomWalletClientParams): CustomWalletClient;

package/dist/cjs/utils/createCustomWalletClient.js

@@ -0,0 +1,114 @@
+"use strict";
+// Copyright (c) 2025, Circle Internet Group, Inc.
+// All rights reserved.
+//
+// Circle Internet Group, Inc. CONFIDENTIAL
+//
+// This file includes unpublished proprietary source code of Circle Internet
+// Group, Inc. The copyright notice above does not
+// evidence any actual or intended publication of such source code. Disclosure
+// of this source code or any related proprietary information is strictly
+// prohibited without the express written permission of Circle Internet Group, Inc.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCustomWalletClient = createCustomWalletClient;
+const viem_1 = require("viem");
+const index_js_1 = require("../actions/index.js");
+const chains = __importStar(require("../chains/index.js"));
+const index_js_2 = require("../providers/cross-chain-transfer-protocol/index.js");
+const index_js_3 = require("../providers/solana/index.js");
+const index_js_4 = require("../providers/uniswap/index.js");
+const createConfig_js_1 = require("./createConfig.js");
+/**
+ * Creates a client with a custom wallet provider transport.
+ *
+ * @param params - The parameters for creating the client
+ * @returns A configured Circle client instance with custom wallet support
+ *
+ * @example
+ * Initialize a client with Fireblocks provider
+ * ```typescript
+ * import { createCustomWalletClient } from '@circle-fin/usdckit/utils'
+ * import { custom } from 'viem'
+ * import { FireblocksWeb3Provider } from '@fireblocks/fireblocks-web3-provider'
+ *
+ * const config = {
+ *   apiKey: process.env.FIREBLOCKS_API_KEY || '',
+ *   privateKey: process.env.FIREBLOCKS_API_PRIVATE_KEY_PATH || '',
+ *   vaultAccountIds: ['2'],
+ *   apiBaseUrl: ApiBaseUrl.Sandbox,
+ * };
+ *
+ * const client = createCustomWalletClient({
+ *   defaultChain: chains.ETH_SEPOLIA,
+ *   chains: [chains.ETH_SEPOLIA, chains.MATIC_AMOY],
+ *   customTransportFactory: ({ chainId }) =>
+ *     custom(
+ *       new FireblocksWeb3Provider({
+ *         ...config,
+ *         chainId,
+ *       }),
+ *     ),
+ * });
+ * ```
+ */
+function createCustomWalletClient(params) {
+    const { defaultChain = chains.ETH_SEPOLIA, chains: userChains = Object.values(chains), customTransportFactory, } = params;
+    const configuredChains = userChains.some((chain) => chain.id === defaultChain.id)
+        ? userChains
+        : [defaultChain, ...userChains];
+    const transportProviders = [
+        (0, index_js_2.http)({}),
+        (0, index_js_3.http)({}),
+        customTransportFactory({ chainId: defaultChain.id }),
+    ];
+    const transport = (0, viem_1.fallback)(transportProviders);
+    const _client = (0, viem_1.createClient)({ chain: defaultChain, transport });
+    // Create a config and bind it onto the client.
+    // Note: By default, we build config with configured chains only.
+    // Note: this step must occur before extending actions, otherwise the config won't be closured into each action calls.
+    _client.config = (0, createConfig_js_1.createConfig)({
+        chains: configuredChains,
+        transportFactory: customTransportFactory,
+    });
+    const client = _client
+        .extend(viem_1.publicActions)
+        .extend(viem_1.walletActions)
+        .extend(index_js_3.actions)
+        .extend(index_js_2.actions)
+        .extend(index_js_4.actions)
+        .extend(index_js_1.actions);
+    return client;
+}

package/dist/cjs/utils/createCustomWalletClient.test.d.ts

@@ -0,0 +1 @@
+export {};