@circle-fin/usdckit 0.21.0 → 0.22.0

package/dist/cjs/providers/circle-wallets/index.js

@@ -24,11 +24,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FEE_LEVEL_WITH_PREPARE = exports.SUPPORTED_CHAINS_FAUCET = exports.SUPPORTED_CHAINS = exports.DEFAULT_WALLET_SET_NAME = exports.NAME = void 0;
+exports.FEE_LEVEL_WITH_PREPARE = exports.SUPPORTED_CONTRACT_QUERY_CHAINS = exports.SUPPORTED_CHAINS_FAUCET = exports.SUPPORTED_CHAINS = exports.DEFAULT_WALLET_SET_NAME = exports.NAME = void 0;
 exports.extractChain = extractChain;
 exports.extractChainFaucet = extractChainFaucet;
+exports.extractChainQueryContract = extractChainQueryContract;
+exports.getBlockchainForSigning = getBlockchainForSigning;
 const index_js_1 = require("../../chains/index.js");
+const index_js_2 = require("../../errors/index.js");
 const extractChain_js_1 = require("../../extractChain.js");
+const raise_js_1 = require("../../utils/raise.js");
 exports.NAME = 'circle-wallets';
 exports.DEFAULT_WALLET_SET_NAME = 'default';
 exports.SUPPORTED_CHAINS = [
@@ -56,13 +60,46 @@ exports.SUPPORTED_CHAINS_FAUCET = [
     index_js_1.OP_SEPOLIA,
     index_js_1.UNI_SEPOLIA,
 ];
+// https://developers.circle.com/api-reference/contracts/smart-contract-platform/query-contract
+exports.SUPPORTED_CONTRACT_QUERY_CHAINS = [
+    index_js_1.ETH,
+    index_js_1.ETH_SEPOLIA,
+    index_js_1.MATIC,
+    index_js_1.MATIC_AMOY,
+    index_js_1.ARB,
+    index_js_1.ARB_SEPOLIA,
+    index_js_1.UNI,
+    index_js_1.UNI_SEPOLIA,
+    index_js_1.BASE,
+    index_js_1.BASE_SEPOLIA,
+    index_js_1.OP,
+    index_js_1.OP_SEPOLIA,
+];
 function extractChain({ id, }) {
     return (0, extractChain_js_1.extractChain)({ id, chains: exports.SUPPORTED_CHAINS });
 }
 function extractChainFaucet({ id }) {
     return (0, extractChain_js_1.extractChain)({ id, chains: exports.SUPPORTED_CHAINS_FAUCET });
 }
+function extractChainQueryContract({ id }) {
+    return (0, extractChain_js_1.extractChain)({ id, chains: exports.SUPPORTED_CONTRACT_QUERY_CHAINS });
+}
+/**
+ * Returns the blockchain for Circle Signing API based on the chain.
+ * @see https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/sign-transaction
+ *
+ * @param chain - The chain to get the blockchain for signing.
+ * @returns The blockchain for signing.
+ */
+function getBlockchainForSigning(chain) {
+    if (chain.blockchainVm === 'EVM') {
+        return chain.testnet ? 'EVM-TESTNET' : 'EVM';
+    }
+    // Near and Solana are not supported yet
+    (0, raise_js_1.raise)(new index_js_2.UnsupportedChainError());
+}
 __exportStar(require("./actions/index.js"), exports);
 __exportStar(require("./transports/index.js"), exports);
-var index_js_2 = require("./actions/index.js");
-Object.defineProperty(exports, "FEE_LEVEL_WITH_PREPARE", { enumerable: true, get: function () { return index_js_2.FEE_LEVEL_WITH_PREPARE; } });
+__exportStar(require("./utils/index.js"), exports);
+var index_js_3 = require("./actions/index.js");
+Object.defineProperty(exports, "FEE_LEVEL_WITH_PREPARE", { enumerable: true, get: function () { return index_js_3.FEE_LEVEL_WITH_PREPARE; } });

package/dist/cjs/providers/circle-wallets/index.test.js

@@ -11,8 +11,57 @@
 // prohibited without the express written permission of Circle Internet Group, Inc.
 Object.defineProperty(exports, "__esModule", { value: true });
 const vitest_1 = require("vitest");
-const index_js_1 = require("./index.js");
+const index_js_1 = require("../../errors/index.js");
+const index_js_2 = require("./index.js");
 (0, vitest_1.test)('Provider and actions are exported', () => {
-    (0, vitest_1.expect)(index_js_1.Provider).toBeDefined();
-    (0, vitest_1.expect)(index_js_1.actions).toBeDefined();
+    (0, vitest_1.expect)(index_js_2.Provider).toBeDefined();
+    (0, vitest_1.expect)(index_js_2.actions).toBeDefined();
+});
+(0, vitest_1.describe)('extractChainQueryContract', () => {
+    (0, vitest_1.test)('should return chain for supported contract query chains', () => {
+        const supportedChains = [
+            { id: 1, name: 'ETH' },
+            { id: 11155111, name: 'ETH_SEPOLIA' },
+            { id: 137, name: 'MATIC' },
+            { id: 80002, name: 'MATIC_AMOY' },
+            { id: 42161, name: 'ARB' },
+            { id: 421614, name: 'ARB_SEPOLIA' },
+            { id: 130, name: 'UNI' },
+            { id: 1301, name: 'UNI_SEPOLIA' },
+            { id: 8453, name: 'BASE' },
+            { id: 84532, name: 'BASE_SEPOLIA' },
+            { id: 10, name: 'OP' },
+            { id: 11155420, name: 'OP_SEPOLIA' },
+        ];
+        for (const { id } of supportedChains) {
+            const result = (0, index_js_2.extractChainQueryContract)({ id });
+            (0, vitest_1.expect)(result).toBeDefined();
+            (0, vitest_1.expect)(result?.id).toBe(id);
+        }
+    });
+    (0, vitest_1.test)('should return undefined for unsupported chain', () => {
+        const unsupportedChainIds = [999, 56, 43114]; // BSC, Avalanche, etc.
+        for (const chainId of unsupportedChainIds) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
+            const result = (0, index_js_2.extractChainQueryContract)({ id: chainId });
+            (0, vitest_1.expect)(result).toBeUndefined();
+        }
+    });
+});
+(0, vitest_1.describe)('getBlockchainForSigning', () => {
+    (0, vitest_1.test)('returns EVM for EVM mainnet', () => {
+        const chain = { blockchainVm: 'EVM', testnet: false };
+        (0, vitest_1.expect)((0, index_js_2.getBlockchainForSigning)(chain)).toBe('EVM');
+    });
+    (0, vitest_1.test)('returns EVM-TESTNET for EVM testnet', () => {
+        const chain = { blockchainVm: 'EVM', testnet: true };
+        (0, vitest_1.expect)((0, index_js_2.getBlockchainForSigning)(chain)).toBe('EVM-TESTNET');
+    });
+    (0, vitest_1.test)('throws for NEAR chains (not supported for signing)', () => {
+        (0, vitest_1.expect)(() => (0, index_js_2.getBlockchainForSigning)({ blockchainVm: 'NEAR', testnet: false })).toThrow(index_js_1.UnsupportedChainError);
+        (0, vitest_1.expect)(() => (0, index_js_2.getBlockchainForSigning)({ blockchainVm: 'NEAR', testnet: true })).toThrow(index_js_1.UnsupportedChainError);
+    });
+    (0, vitest_1.test)('throws UnsupportedChainError for unknown VM', () => {
+        (0, vitest_1.expect)(() => (0, index_js_2.getBlockchainForSigning)({ blockchainVm: 'UNKNOWN', testnet: false })).toThrow(index_js_1.UnsupportedChainError);
+    });
 });

package/dist/cjs/providers/circle-wallets/transports/http.d.ts

@@ -1,6 +1,24 @@
-export declare function http({ apiKey, entitySecret, baseUrl, name, }: {
+import type { Transport } from 'viem';
+export declare function http({ apiKey, entitySecret, baseUrl, name, chainId, timeout, pollingInterval, fallbackTransport, }: {
     apiKey: string;
     entitySecret: string;
     baseUrl?: string;
     name?: string;
+    chainId: number;
+    /**
+     * The polling timeout for the transaction (milliseconds).
+     * If not provided, there is no timeout.
+     */
+    timeout?: number;
+    /**
+     * Interval of polling (milliseconds).
+     * Default is 1000 (1 second).
+     */
+    pollingInterval?: number;
+    /**
+     * The fallback transport is used when the requested method is not supported by the Circle Wallets provider.
+     * By default, it's a http provider that uses the public RPC endpoint.
+     * Set to null to disable the fallback behavior.
+     */
+    fallbackTransport?: Transport | null;
 }): import("viem").CustomTransport;

package/dist/cjs/providers/circle-wallets/transports/http.js

@@ -14,8 +14,8 @@ exports.http = http;
 const viem_1 = require("viem");
 const index_js_1 = require("../index.js");
 const index_js_2 = require("./index.js");
-function http({ apiKey, entitySecret, baseUrl, name = index_js_1.NAME, }) {
-    const provider = new index_js_2.Provider({ apiKey, entitySecret, baseUrl });
+function http({ apiKey, entitySecret, baseUrl, name = index_js_1.NAME, chainId, timeout, pollingInterval, fallbackTransport = (0, viem_1.http)(), }) {
+    const provider = new index_js_2.Provider({ apiKey, entitySecret, baseUrl, chainId, timeout, pollingInterval, fallbackTransport });
     const config = { name, key: name };
     return (0, viem_1.custom)(provider, config);
 }

package/dist/cjs/providers/circle-wallets/transports/http.test.js

@@ -16,10 +16,10 @@ const index_js_2 = require("../index.js");
 const http_js_1 = require("./http.js");
 vitest_1.describe.concurrent('http', () => {
     vitest_1.test.each([
-        [{ apiKey: 'apiKey', entitySecret: 'entitySecret', baseUrl: 'https://example.com', name: 'name' }],
-        [{ apiKey: 'apiKey', entitySecret: 'entitySecret', baseUrl: 'https://example.com', name: undefined }],
-        [{ apiKey: 'apiKey', entitySecret: 'entitySecret', name: 'name' }],
-        [{ apiKey: 'apiKey', entitySecret: 'entitySecret', name: undefined }],
+        [{ apiKey: 'apiKey', entitySecret: 'entitySecret', baseUrl: 'https://example.com', name: 'name', chainId: 1 }],
+        [{ apiKey: 'apiKey', entitySecret: 'entitySecret', baseUrl: 'https://example.com', name: undefined, chainId: 1 }],
+        [{ apiKey: 'apiKey', entitySecret: 'entitySecret', name: 'name', chainId: 1 }],
+        [{ apiKey: 'apiKey', entitySecret: 'entitySecret', name: undefined, chainId: 1 }],
     ])('should create a transport %o', (params) => {
         const transportFn = (0, http_js_1.http)(params);
         const transport = transportFn({ chain: index_js_1.ETH_SEPOLIA });
@@ -29,4 +29,24 @@ vitest_1.describe.concurrent('http', () => {
         (0, vitest_1.expect)(transport.config.type).toEqual('custom');
         (0, vitest_1.expect)(transport.config.request).toEqual(vitest_1.expect.any(Function));
     });
+    (0, vitest_1.test)('should accept timeout parameter', () => {
+        const transportFn = (0, http_js_1.http)({
+            apiKey: 'test-key',
+            entitySecret: 'test-secret',
+            chainId: 1,
+            timeout: 15000,
+        });
+        (0, vitest_1.expect)(transportFn).toEqual(vitest_1.expect.any(Function));
+        const transport = transportFn({ chain: index_js_1.ETH_SEPOLIA });
+        (0, vitest_1.expect)(transport.config.type).toBe('custom');
+    });
+    (0, vitest_1.test)('should accept fallback parameter to be null', () => {
+        const transportFn = (0, http_js_1.http)({
+            apiKey: 'test-key',
+            entitySecret: 'test-secret',
+            chainId: 1,
+            fallbackTransport: null,
+        });
+        (0, vitest_1.expect)(transportFn).toEqual(vitest_1.expect.any(Function));
+    });
 });

package/dist/cjs/providers/circle-wallets/transports/index.d.ts

@@ -1,7 +1,8 @@
 import { Provider as BaseProvider } from '../../index.js';
-import type { Merge, NativeUnits } from '../../../types.js';
+import type { Address, ControlFlowOptions, Merge, NativeUnits } from '../../../types.js';
 import type { CircleDeveloperControlledWalletsClient, CreateWalletSetInput, CreateWalletsInput, GetWalletInput, ListWalletsInput, GetTransactionInput, Blockchain, EstimateTransferFeeInput as _EstimateTransferFeeInput, CreateTransferTransactionInput as _CreateTransferTransactionInput, GetWalletTokenBalanceInput as _GetWalletTokenBalanceInput, NotificationSignaturePublicKeyData as NotificationSignature, Balance, DeriveWalletInput, GetWalletsWithBalancesInput, WalletsWithBalancesDataWalletsInner as WalletWithBalances, SignTypedDataInput as _SignTypedDataInput, SignTransactionInput as _SignTransactionInput, WalletSet, Wallet, Transaction, EstimateTransactionFeeData as EstimateTransactionFee, SignatureResponseData as SignedTypedData, SignTransactionResponseData as SignedTransaction, CreateContractExecutionTransactionInput as _CreateContractExecutionTransactionInput, EstimateContractExecutionFeeInput as _EstimateContractExecutionFeeInput, RequestTestnetTokensInput } from '@circle-fin/developer-controlled-wallets';
 import type { CircleSmartContractPlatformClient, ImportContractInput as _ImportContractInput } from '@circle-fin/smart-contract-platform';
+import type { Hash, Hex, RpcTransactionRequest, ExactPartial, TransactionRequest, Transport } from 'viem';
 export { http } from './http.js';
 export type { CreateWalletsInput, CreateWalletSetInput, GetTransactionInput, GetWalletInput, ListWalletsInput, Balance, Transaction, Wallet, WalletSet, EstimateTransactionFee, DeriveWalletInput, GetWalletsWithBalancesInput, WalletWithBalances, SignedTypedData, SignedTransaction, NotificationSignature, RequestTestnetTokensInput, };
 export type ListTransactionsInput = {
@@ -21,7 +22,8 @@ export type EstimateTransferFeeInput = Omit<_EstimateTransferFeeInput, 'amount'>
 export type CreateTransactionInput = Omit<_CreateTransferTransactionInput, 'walletId' | 'amount'> & Partial<Pick<_CreateTransferTransactionInput, 'walletId' | 'amount'>> & {
     amounts?: NativeUnits[];
     sourceAddress?: string;
-};
+    waitForTransactionHash?: boolean;
+} & ControlFlowOptions;
 export type GetNotificationSignatureInput = {
     kid: string;
 };
@@ -38,7 +40,8 @@ export type CreateContractExecutionTransactionInput = Merge<Omit<_CreateContract
     sourceAddress?: string;
     blockchain?: Blockchain;
     callData?: `0x${string}`;
-}>;
+    waitForTransactionHash?: boolean;
+} & ControlFlowOptions>;
 export type EstimateContractExecutionFeeInput = Merge<_EstimateContractExecutionFeeInput, {
     abiFunctionSignature?: string;
     abiParameters?: any[];
@@ -48,6 +51,9 @@ export type ImportContractInput = _ImportContractInput & {
     sourceAddress?: string;
     blockchain?: Blockchain;
 };
+export type WalletSwitchEthereumChainInput = {
+    chainId: Hex;
+};
 export type EIP1474Methods = [
     {
         Method: 'circle_createWalletSet';
@@ -138,23 +144,83 @@ export type EIP1474Methods = [
         Method: 'circle_requestTestnetTokens';
         Parameters: Parameters<Provider['circle_requestTestnetTokens']>;
         ReturnType: Awaited<ReturnType<Provider['circle_requestTestnetTokens']>>;
+    },
+    {
+        Method: 'eth_chainId';
+        Parameters: Parameters<Provider['eth_chainId']>;
+        ReturnType: Awaited<ReturnType<Provider['eth_chainId']>>;
+    },
+    {
+        Method: 'eth_getBalance';
+        Parameters: Parameters<Provider['eth_getBalance']>;
+        ReturnType: Awaited<ReturnType<Provider['eth_getBalance']>>;
+    },
+    {
+        Method: 'eth_signTypedData_v4';
+        Parameters: Parameters<Provider['eth_signTypedData_v4']>;
+        ReturnType: Awaited<ReturnType<Provider['eth_signTypedData_v4']>>;
+    },
+    {
+        Method: 'eth_sendTransaction';
+        Parameters: Parameters<Provider['eth_sendTransaction']>;
+        ReturnType: Awaited<ReturnType<Provider['eth_sendTransaction']>>;
+    },
+    {
+        Method: 'eth_call';
+        Parameters: Parameters<Provider['eth_call']>;
+        ReturnType: Awaited<ReturnType<Provider['eth_call']>>;
+    },
+    {
+        Method: 'eth_estimateGas';
+        Parameters: Parameters<Provider['eth_estimateGas']>;
+        ReturnType: Awaited<ReturnType<Provider['eth_estimateGas']>>;
+    },
+    {
+        Method: 'eth_signTransaction';
+        Parameters: Parameters<Provider['eth_signTransaction']>;
+        ReturnType: Awaited<ReturnType<Provider['eth_signTransaction']>>;
     }
 ];
 export declare const SENTINEL_FEES = -1n;
 export declare class Provider extends BaseProvider {
     protected readonly devc: CircleDeveloperControlledWalletsClient;
     protected readonly scp: CircleSmartContractPlatformClient;
-    constructor({ apiKey, entitySecret, baseUrl }: {
+    protected readonly pollingInterval: number;
+    private readonly fallback?;
+    protected readonly chainId: number;
+    /**
+     * The polling timeout for the transaction.
+     * If not provided, there is no timeout.
+     */
+    protected timeout?: number;
+    constructor({ apiKey, entitySecret, baseUrl, chainId, timeout, pollingInterval, fallbackTransport, }: {
         apiKey: string;
         entitySecret: string;
         baseUrl?: string;
+        chainId: number;
+        timeout?: number;
+        pollingInterval?: number;
+        fallbackTransport?: Transport | null;
     });
-    circle_createWalletSet(params: CreateWalletSetInput): Promise<WalletSet>;
-    circle_createWallets(params: CreateWalletsInput): Promise<[Wallet, ...Wallet[]]>;
-    circle_getWallet(params: GetWalletInput): Promise<Wallet>;
-    circle_listWallets(params: ListWalletsInput): Promise<Wallet[]>;
-    circle_getWalletTokenBalance(params: GetWalletTokenBalanceInput): Promise<Balance[]>;
-    circle_estimateTransferFee(params: EstimateTransferFeeInput): Promise<{
+    get defaultSignal(): AbortSignal | undefined;
+    protected eth_chainId(): Hex;
+    protected eth_getBalance(address: Address, blockTag?: string): Promise<Hex>;
+    protected eth_call(params: ExactPartial<TransactionRequest>, blockIdentifier?: string): Promise<Hex>;
+    protected eth_sendTransaction(params: RpcTransactionRequest): Promise<Hash>;
+    /**
+     * Parses fee parameters from RpcTransactionRequest and converts to Circle API format.
+     * @param params - The RPC transaction request containing fee parameters
+     * @returns Promise resolving to the fee configuration for Circle API
+     */
+    private parseFeeParams;
+    protected eth_estimateGas(params: RpcTransactionRequest, _blockIdentifier?: string): Promise<Hex>;
+    private waitForTransactionWithHash;
+    protected circle_createWalletSet(params: CreateWalletSetInput): Promise<WalletSet>;
+    protected circle_createWallets(params: CreateWalletsInput): Promise<[Wallet, ...Wallet[]]>;
+    protected circle_getWallet(params: GetWalletInput): Promise<Wallet>;
+    protected circle_listWallets(params: ListWalletsInput): Promise<Wallet[]>;
+    protected circle_getWalletTokenBalance(params: GetWalletTokenBalanceInput): Promise<Balance[]>;
+    protected circle_estimateTransferFee(params: EstimateTransferFeeInput): Promise<{
         high: {
             gasLimit: `${number}` | "" | undefined;
             maxFee: `${number}` | "" | undefined;
@@ -183,14 +249,24 @@ export declare class Provider extends BaseProvider {
         verificationGasLimit?: string;
         preVerificationGas?: string;
     }>;
-    circle_createTransaction(params: CreateTransactionInput): Promise<Transaction>;
-    circle_getTransaction(params: GetTransactionInput): Promise<Transaction>;
-    circle_getNotificationSignature(params: GetNotificationSignatureInput): Promise<NotificationSignature>;
-    circle_deriveWallet(params: DeriveWalletInput): Promise<Wallet>;
-    circle_getWalletsWithBalances(params: GetWalletsWithBalancesInput): Promise<Wallet[]>;
-    circle_signTypedData(params: SignTypedDataInput): Promise<SignedTypedData>;
-    circle_signTransaction(params: SignTransactionInput): Promise<SignedTransaction>;
-    circle_estimateContractExecutionFee(params: EstimateContractExecutionFeeInput): Promise<{
+    protected circle_createTransaction(params: CreateTransactionInput): Promise<Transaction>;
+    protected circle_getTransaction(params: GetTransactionInput): Promise<Transaction>;
+    protected circle_getNotificationSignature(params: GetNotificationSignatureInput): Promise<NotificationSignature>;
+    protected circle_deriveWallet(params: DeriveWalletInput): Promise<Wallet>;
+    protected circle_getWalletsWithBalances(params: GetWalletsWithBalancesInput): Promise<Wallet[]>;
+    protected circle_signTypedData(params: SignTypedDataInput): Promise<SignedTypedData>;
+    protected eth_signTypedData_v4(address: Address, message: string): Promise<string>;
+    protected circle_signTransaction(params: SignTransactionInput): Promise<SignedTransaction>;
+    /**
+     * Sign a transaction using the Circle Signing API
+     * @see https://learn.circle.com/w3s/signing-apis
+     * @param params - The transaction request
+     * @returns The signed transaction
+     */
+    protected eth_signTransaction(params: RpcTransactionRequest & {
+        chainId?: Hex;
+    }): Promise<Hex>;
+    protected circle_estimateContractExecutionFee(params: EstimateContractExecutionFeeInput): Promise<{
         high: {
             gasLimit: `${number}` | "" | undefined;
             maxFee: `${number}` | "" | undefined;
@@ -219,8 +295,12 @@ export declare class Provider extends BaseProvider {
         verificationGasLimit?: string;
         preVerificationGas?: string;
     }>;
-    circle_createContractExecutionTransaction(params: CreateContractExecutionTransactionInput): Promise<Transaction>;
-    circle_importContract(params: ImportContractInput): Promise<import("@circle-fin/smart-contract-platform").Contract>;
-    circle_listTransactions(params: ListTransactionsInput): Promise<Transaction[]>;
-    circle_requestTestnetTokens(params: RequestTestnetTokensInput): Promise<void>;
+    protected circle_createContractExecutionTransaction(params: CreateContractExecutionTransactionInput): Promise<Transaction>;
+    protected circle_importContract(params: ImportContractInput): Promise<import("@circle-fin/smart-contract-platform").Contract>;
+    protected circle_listTransactions(params: ListTransactionsInput): Promise<Transaction[]>;
+    protected circle_requestTestnetTokens(params: RequestTestnetTokensInput): Promise<void>;
+    request({ method, params }: {
+        method: string;
+        params?: unknown[];
+    }): Promise<unknown>;
 }