@circle-fin/usdckit 0.21.1 → 0.22.0

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

@@ -8,13 +8,17 @@
 // 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 { setTimeout } from 'node:timers/promises';
 import { initiateDeveloperControlledWalletsClient } from '@circle-fin/developer-controlled-wallets';
 import { initiateSmartContractPlatformClient } from '@circle-fin/smart-contract-platform';
-import { formatGwei } from 'viem';
-import { ErrorWithCause as Error } from '../../../errors/index.js';
+import { formatEther, formatGwei, hexToBigInt, numberToHex, hexToNumber, MethodNotFoundRpcError, http } from 'viem';
+import { ErrorWithCause as Error, UnsupportedChainError } from '../../../errors/index.js';
 import { VERSION } from '../../../metadata.js';
 import { generateIdempotencyKey } from '../../../utils/generateIdempotencyKey.js';
+import { parseUnits } from '../../../utils/parseUnits.js';
+import { raise } from '../../../utils/raise.js';
 import { Provider as BaseProvider } from '../../index.js';
+import { extractChain, extractChainQueryContract, getBlockchainForSigning } from '../index.js';
 export { http } from './http.js';
 // Sentinel value for gas fees to be empty
 export const SENTINEL_FEES = -1n;
@@ -43,10 +47,19 @@ function addBuffersToLevel(data) {
         priorityFee: data.priorityFee && addBuffer(data.priorityFee),
     };
 }
+const DEFAULT_POLLING_INTERVAL = 1000;
 export class Provider extends BaseProvider {
     devc;
     scp;
-    constructor({ apiKey, entitySecret, baseUrl }) {
+    pollingInterval;
+    fallback;
+    chainId;
+    /**
+     * The polling timeout for the transaction.
+     * If not provided, there is no timeout.
+     */
+    timeout;
+    constructor({ apiKey, entitySecret, baseUrl, chainId, timeout, pollingInterval, fallbackTransport = http(), }) {
         super();
         this.devc = initiateDeveloperControlledWalletsClient({
             apiKey,
@@ -60,6 +73,187 @@ export class Provider extends BaseProvider {
             baseUrl,
             userAgent: `Circle-USDCKit/${VERSION}`,
         });
+        this.chainId = chainId;
+        // Currently, the timeout is only used for the polling operation.
+        this.timeout = timeout;
+        this.pollingInterval = pollingInterval ?? DEFAULT_POLLING_INTERVAL;
+        if (this.pollingInterval <= 0) {
+            throw new Error('Polling interval must be greater than 0');
+        }
+        if (fallbackTransport !== null) {
+            const chain = extractChain({ id: this.chainId });
+            if (chain !== undefined) {
+                this.fallback = fallbackTransport({ chain }).request;
+            }
+        }
+    }
+    get defaultSignal() {
+        return this.timeout !== undefined ? AbortSignal.timeout(this.timeout) : undefined;
+    }
+    eth_chainId() {
+        if (this.chainId === undefined) {
+            throw new Error('Chain ID is not set');
+        }
+        return numberToHex(this.chainId);
+    }
+    async eth_getBalance(address, blockTag = 'latest') {
+        // Only support 'latest' block (Circle API doesn't support historical queries)
+        if (blockTag !== 'latest') {
+            throw new Error('Only "latest" block tag is supported');
+        }
+        const chain = extractChain({ id: this.chainId }) ?? raise(new UnsupportedChainError());
+        const tokenBalances = await this.circle_getWalletTokenBalance({
+            address,
+            blockchain: chain.blockchainId,
+            tokenAddress: null, // null = native token
+        });
+        if (tokenBalances.length === 0) {
+            return '0x0';
+        }
+        const balance = tokenBalances[0];
+        const balanceWei = parseUnits(balance.amount, balance.token.decimals ?? chain.nativeCurrency.decimals);
+        return numberToHex(balanceWei);
+    }
+    async eth_call(params, blockIdentifier = 'latest') {
+        // NOTE: https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_call
+        // In JSON-RPC `eth_call` spec, blockIdentifier is a required parameter.
+        // It is a hex string of the block number, 'latest', 'earliest', 'pending', 'safe' or 'finalized'.
+        // Although Circle's query contract API does not support it, we still add it to be compatible with the JSON-RPC spec.
+        if (blockIdentifier !== 'latest') {
+            throw new Error('Only `latest` block identifier is supported');
+        }
+        // Since Circle's query contract API does not support some transaction params,
+        // to prevent misuse, we throw an error if they are provided.
+        const unsupportedTransactionParams = ['gas', 'gasPrice', 'maxFeePerGas', 'maxPriorityFeePerGas', 'nonce', 'value'];
+        if (unsupportedTransactionParams.some((param) => params[param] !== undefined)) {
+            throw new Error(`Unsupported transaction params: ${unsupportedTransactionParams.join(', ')}`);
+        }
+        // Provider's chainId is used to determine the blockchain
+        // When the chain is not supported by Circle's query contract API, throw MethodNotFoundRpcError to fallback.
+        const chain = extractChainQueryContract({ id: this.chainId }) ??
+            raise(new MethodNotFoundRpcError(new UnsupportedChainError(), { method: 'eth_call' }));
+        const response = await this.scp.queryContract({
+            blockchain: chain.blockchainId,
+            address: params.to, // Contract address
+            callData: params.data,
+            fromAddress: params.from,
+        });
+        return response.data.outputData;
+    }
+    async eth_sendTransaction(params) {
+        // Provider's chainId is used to determine the blockchain
+        const chain = extractChain({ id: this.chainId }) ?? raise(new UnsupportedChainError());
+        // Convert fee parameters to Circle API fee configuration
+        const fee = await this.parseFeeParams(params);
+        const value = params.value && formatEther(hexToBigInt(params.value));
+        // If `data` is provided, create a contract execution transaction.
+        // Otherwise, create a transfer transaction.
+        const transaction = params.data
+            ? await this.circle_createContractExecutionTransaction({
+                sourceAddress: params.from,
+                blockchain: chain.blockchainId,
+                amount: value,
+                fee,
+                contractAddress: params.to,
+                callData: params.data,
+            })
+            : await this.circle_createTransaction({
+                sourceAddress: params.from,
+                blockchain: chain.blockchainId,
+                amounts: [value],
+                fee,
+                destinationAddress: params.to,
+            });
+        return transaction.txHash;
+    }
+    /**
+     * 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
+     */
+    async parseFeeParams(params) {
+        const { gas, gasPrice, maxFeePerGas, maxPriorityFeePerGas } = params;
+        // Legacy (type 0x0, 0x1)  (~= params.type === 0x0 or 0x1)
+        if (gasPrice !== undefined) {
+            const gasLimitHex = gas ?? (await this.eth_estimateGas(params));
+            const gasLimit = hexToBigInt(gasLimitHex).toString();
+            return {
+                config: {
+                    gasLimit,
+                    gasPrice: formatGwei(hexToBigInt(gasPrice)),
+                },
+                type: 'gas',
+            };
+        }
+        // EIP-1559 (type 0x2)  (~= params.type === 0x2)
+        if (maxFeePerGas !== undefined || maxPriorityFeePerGas !== undefined) {
+            const gasLimitHex = gas ?? (await this.eth_estimateGas(params));
+            const gasLimit = hexToBigInt(gasLimitHex).toString();
+            return {
+                config: {
+                    gasLimit,
+                    maxFee: maxFeePerGas ? formatGwei(hexToBigInt(maxFeePerGas)) : '',
+                    priorityFee: maxPriorityFeePerGas ? formatGwei(hexToBigInt(maxPriorityFeePerGas)) : '',
+                },
+                type: 'absolute',
+            };
+        }
+        // Default - no fee pricing params provided, use default HIGH fee level
+        return {
+            config: {
+                feeLevel: 'HIGH',
+                // @ts-expect-error - gasLimit is not in the FeeLevel config type but Circle API supports it
+                gasLimit: gas !== undefined ? hexToBigInt(gas).toString() : undefined,
+            },
+            type: 'level',
+        };
+    }
+    async eth_estimateGas(params, _blockIdentifier) {
+        // NOTE: blockIdentifier parameter are not supported by Circle API
+        // Circle's fee estimation APIs only work with current network state (latest block)
+        if (_blockIdentifier && _blockIdentifier !== 'latest') {
+            throw new Error('Only `latest` block identifier is supported');
+        }
+        const chain = extractChain({ id: this.chainId }) ?? raise(new UnsupportedChainError());
+        const value = params.value && formatEther(hexToBigInt(params.value));
+        // If `data` is provided, estimate contract execution gas.
+        // Otherwise, estimate transfer gas.
+        const estimate = params.data
+            ? await this.circle_estimateContractExecutionFee({
+                source: {
+                    sourceAddress: params.from,
+                    blockchain: chain.blockchainId,
+                },
+                amount: value,
+                contractAddress: params.to,
+                callData: params.data,
+            })
+            : await this.circle_estimateTransferFee({
+                sourceAddress: params.from,
+                blockchain: chain.blockchainId,
+                amounts: [value],
+                destinationAddress: params.to,
+            });
+        // NOTE: gasLimit should ideally be the same across all fee levels (high/medium/low).
+        // By default, use HIGH fee level for gas estimation.
+        const { gasLimit } = estimate.high;
+        return numberToHex(BigInt(gasLimit));
+    }
+    async waitForTransactionWithHash(transactionId, signal) {
+        let transaction;
+        do {
+            transaction = await this.circle_getTransaction({ id: transactionId });
+            const { state, errorReason, errorDetails } = transaction;
+            switch (state) {
+                case 'CANCELLED':
+                case 'DENIED':
+                case 'FAILED':
+                    throw new Error(errorDetails, { cause: { code: errorReason, message: errorDetails } });
+                default:
+                    await setTimeout(this.pollingInterval, null, { signal: signal ?? this.defaultSignal });
+            }
+        } while (transaction.txHash == null);
+        return transaction;
     }
     async circle_createWalletSet(params) {
         const response = await this.devc.createWalletSet(params);
@@ -179,6 +373,9 @@ export class Provider extends BaseProvider {
             }
         }
         const response = await this.devc.createTransaction(params);
+        if (params.waitForTransactionHash ?? true) {
+            return await this.waitForTransactionWithHash(response.data.id, params.signal);
+        }
         // NOTE: `createTransaction` does not produce the same structure as `getTransaction`
         // HACK: Return the same structure as `getTransaction`.
         return await this.circle_getTransaction({ id: response.data.id });
@@ -217,6 +414,15 @@ export class Provider extends BaseProvider {
         const response = await this.devc.signTypedData(params);
         return response.data;
     }
+    async eth_signTypedData_v4(address, message) {
+        const chain = extractChain({ id: this.chainId }) ?? raise(new UnsupportedChainError());
+        const { signature } = await this.circle_signTypedData({
+            address,
+            blockchain: chain.blockchainId,
+            data: message,
+        });
+        return signature;
+    }
     async circle_signTransaction(params) {
         params = { ...params };
         // Support usage with `address` and `blockchain`
@@ -234,6 +440,39 @@ export class Provider extends BaseProvider {
         const response = await this.devc.signTransaction(params);
         return response.data;
     }
+    /**
+     * 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
+     */
+    async eth_signTransaction(params) {
+        // TODO: add logger to the Provider to warn the user:
+        // If you are using an EVM wallet, please be careful not to use it interchangeably with your "native" wallet.
+        // For more details, refer to: https://learn.circle.com/w3s/sign-tx-evm#prerequisites
+        const chainId = this.eth_chainId();
+        const chain = extractChain({ id: hexToNumber(chainId) }) ?? raise(new UnsupportedChainError());
+        // The chainId is required for the Circle Signing API.
+        // If chainId is not provided in the params, use the chainId from the Provider.
+        params.chainId = params.chainId ?? chainId;
+        const { from } = params;
+        if (from === undefined) {
+            throw new Error('`from` is required');
+        }
+        const blockchain = getBlockchainForSigning(chain);
+        const wallets = await this.circle_listWallets({
+            address: from,
+            blockchain,
+        });
+        if (wallets.length !== 1) {
+            throw new Error(`Expected exactly 1 wallet for address ${from} on ${blockchain}, but found ${wallets.length}`);
+        }
+        const response = await this.circle_signTransaction({
+            walletId: wallets[0].id,
+            transaction: JSON.stringify(params),
+        });
+        return response.signedTransaction;
+    }
     async circle_estimateContractExecutionFee(params) {
         // @ts-expect-error: `callData` field is missing from SDKv1
         const response = await this.devc.estimateContractExecutionFee(params);
@@ -273,6 +512,9 @@ export class Provider extends BaseProvider {
             }
         }
         const response = await this.devc.createContractExecutionTransaction(params);
+        if (params.waitForTransactionHash ?? true) {
+            return await this.waitForTransactionWithHash(response.data.id, params.signal);
+        }
         // NOTE: `createContractExecutionTransaction` does not produce the same structure as `getTransaction`
         // HACK: Return the same structure as `getTransaction`.
         return await this.circle_getTransaction({ id: response.data.id });
@@ -293,4 +535,16 @@ export class Provider extends BaseProvider {
     async circle_requestTestnetTokens(params) {
         await this.devc.requestTestnetTokens(params);
     }
+    // Override the request method to support fallback to the embedded RPC provider.
+    async request({ method, params = [] }) {
+        try {
+            return await super.request({ method, params });
+        }
+        catch (error) {
+            if (error instanceof MethodNotFoundRpcError && this.fallback !== undefined) {
+                return this.fallback({ method, params });
+            }
+            throw error;
+        }
+    }
 }