@circle-fin/usdckit 0.21.0 → 0.22.0

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

@@ -9,7 +9,9 @@
 // of this source code or any related proprietary information is strictly
 // prohibited without the express written permission of Circle Internet Group, Inc.
 import { ARB, ARB_SEPOLIA, AVAX, AVAX_FUJI, BASE, BASE_SEPOLIA, ETH, ETH_SEPOLIA, MATIC, MATIC_AMOY, OP, OP_SEPOLIA, UNI, UNI_SEPOLIA, } from '../../chains/index.js';
+import { UnsupportedChainError } from '../../errors/index.js';
 import { extractChain as _extractChain } from '../../extractChain.js';
+import { raise } from '../../utils/raise.js';
 export const NAME = 'circle-wallets';
 export const DEFAULT_WALLET_SET_NAME = 'default';
 export const SUPPORTED_CHAINS = [
@@ -37,12 +39,45 @@ export const SUPPORTED_CHAINS_FAUCET = [
     OP_SEPOLIA,
     UNI_SEPOLIA,
 ];
+// https://developers.circle.com/api-reference/contracts/smart-contract-platform/query-contract
+export const SUPPORTED_CONTRACT_QUERY_CHAINS = [
+    ETH,
+    ETH_SEPOLIA,
+    MATIC,
+    MATIC_AMOY,
+    ARB,
+    ARB_SEPOLIA,
+    UNI,
+    UNI_SEPOLIA,
+    BASE,
+    BASE_SEPOLIA,
+    OP,
+    OP_SEPOLIA,
+];
 export function extractChain({ id, }) {
     return _extractChain({ id, chains: SUPPORTED_CHAINS });
 }
 export function extractChainFaucet({ id }) {
     return _extractChain({ id, chains: SUPPORTED_CHAINS_FAUCET });
 }
+export function extractChainQueryContract({ id }) {
+    return _extractChain({ id, chains: 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.
+ */
+export function getBlockchainForSigning(chain) {
+    if (chain.blockchainVm === 'EVM') {
+        return chain.testnet ? 'EVM-TESTNET' : 'EVM';
+    }
+    // Near and Solana are not supported yet
+    raise(new UnsupportedChainError());
+}
 export * from './actions/index.js';
 export * from './transports/index.js';
+export * from './utils/index.js';
 export { FEE_LEVEL_WITH_PREPARE } from './actions/index.js';

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

@@ -8,9 +8,58 @@
 // 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.
-import { test, expect } from 'vitest';
-import { Provider, actions } from './index.js';
+import { test, expect, describe } from 'vitest';
+import { UnsupportedChainError } from '../../errors/index.js';
+import { Provider, actions, extractChainQueryContract, getBlockchainForSigning } from './index.js';
 test('Provider and actions are exported', () => {
     expect(Provider).toBeDefined();
     expect(actions).toBeDefined();
 });
+describe('extractChainQueryContract', () => {
+    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 = extractChainQueryContract({ id });
+            expect(result).toBeDefined();
+            expect(result?.id).toBe(id);
+        }
+    });
+    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 = extractChainQueryContract({ id: chainId });
+            expect(result).toBeUndefined();
+        }
+    });
+});
+describe('getBlockchainForSigning', () => {
+    test('returns EVM for EVM mainnet', () => {
+        const chain = { blockchainVm: 'EVM', testnet: false };
+        expect(getBlockchainForSigning(chain)).toBe('EVM');
+    });
+    test('returns EVM-TESTNET for EVM testnet', () => {
+        const chain = { blockchainVm: 'EVM', testnet: true };
+        expect(getBlockchainForSigning(chain)).toBe('EVM-TESTNET');
+    });
+    test('throws for NEAR chains (not supported for signing)', () => {
+        expect(() => getBlockchainForSigning({ blockchainVm: 'NEAR', testnet: false })).toThrow(UnsupportedChainError);
+        expect(() => getBlockchainForSigning({ blockchainVm: 'NEAR', testnet: true })).toThrow(UnsupportedChainError);
+    });
+    test('throws UnsupportedChainError for unknown VM', () => {
+        expect(() => getBlockchainForSigning({ blockchainVm: 'UNKNOWN', testnet: false })).toThrow(UnsupportedChainError);
+    });
+});

package/dist/esm/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/esm/providers/circle-wallets/transports/http.js

@@ -8,11 +8,11 @@
 // 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.
-import { custom } from 'viem';
+import { custom, http as viemHttp } from 'viem';
 import { NAME } from '../index.js';
 import { Provider } from './index.js';
-export function http({ apiKey, entitySecret, baseUrl, name = NAME, }) {
-    const provider = new Provider({ apiKey, entitySecret, baseUrl });
+export function http({ apiKey, entitySecret, baseUrl, name = NAME, chainId, timeout, pollingInterval, fallbackTransport = viemHttp(), }) {
+    const provider = new Provider({ apiKey, entitySecret, baseUrl, chainId, timeout, pollingInterval, fallbackTransport });
     const config = { name, key: name };
     return custom(provider, config);
 }

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

@@ -14,10 +14,10 @@ import { NAME } from '../index.js';
 import { http } from './http.js';
 describe.concurrent('http', () => {
     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 = http(params);
         const transport = transportFn({ chain: ETH_SEPOLIA });
@@ -27,4 +27,24 @@ describe.concurrent('http', () => {
         expect(transport.config.type).toEqual('custom');
         expect(transport.config.request).toEqual(expect.any(Function));
     });
+    test('should accept timeout parameter', () => {
+        const transportFn = http({
+            apiKey: 'test-key',
+            entitySecret: 'test-secret',
+            chainId: 1,
+            timeout: 15000,
+        });
+        expect(transportFn).toEqual(expect.any(Function));
+        const transport = transportFn({ chain: ETH_SEPOLIA });
+        expect(transport.config.type).toBe('custom');
+    });
+    test('should accept fallback parameter to be null', () => {
+        const transportFn = http({
+            apiKey: 'test-key',
+            entitySecret: 'test-secret',
+            chainId: 1,
+            fallbackTransport: null,
+        });
+        expect(transportFn).toEqual(expect.any(Function));
+    });
 });

package/dist/esm/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>;
 }