@circle-fin/usdckit 0.21.0 → 0.22.0

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

@@ -11,13 +11,17 @@
 // prohibited without the express written permission of Circle Internet Group, Inc.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Provider = exports.SENTINEL_FEES = exports.http = void 0;
+const promises_1 = require("node:timers/promises");
 const developer_controlled_wallets_1 = require("@circle-fin/developer-controlled-wallets");
 const smart_contract_platform_1 = require("@circle-fin/smart-contract-platform");
 const viem_1 = require("viem");
 const index_js_1 = require("../../../errors/index.js");
 const metadata_js_1 = require("../../../metadata.js");
 const generateIdempotencyKey_js_1 = require("../../../utils/generateIdempotencyKey.js");
+const parseUnits_js_1 = require("../../../utils/parseUnits.js");
+const raise_js_1 = require("../../../utils/raise.js");
 const index_js_2 = require("../../index.js");
+const index_js_3 = require("../index.js");
 var http_js_1 = require("./http.js");
 Object.defineProperty(exports, "http", { enumerable: true, get: function () { return http_js_1.http; } });
 // Sentinel value for gas fees to be empty
@@ -47,10 +51,19 @@ function addBuffersToLevel(data) {
         priorityFee: data.priorityFee && addBuffer(data.priorityFee),
     };
 }
+const DEFAULT_POLLING_INTERVAL = 1000;
 class Provider extends index_js_2.Provider {
     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 = (0, viem_1.http)(), }) {
         super();
         this.devc = (0, developer_controlled_wallets_1.initiateDeveloperControlledWalletsClient)({
             apiKey,
@@ -64,6 +77,187 @@ class Provider extends index_js_2.Provider {
             baseUrl,
             userAgent: `Circle-USDCKit/${metadata_js_1.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 index_js_1.ErrorWithCause('Polling interval must be greater than 0');
+        }
+        if (fallbackTransport !== null) {
+            const chain = (0, index_js_3.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 index_js_1.ErrorWithCause('Chain ID is not set');
+        }
+        return (0, viem_1.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 index_js_1.ErrorWithCause('Only "latest" block tag is supported');
+        }
+        const chain = (0, index_js_3.extractChain)({ id: this.chainId }) ?? (0, raise_js_1.raise)(new index_js_1.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 = (0, parseUnits_js_1.parseUnits)(balance.amount, balance.token.decimals ?? chain.nativeCurrency.decimals);
+        return (0, viem_1.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 index_js_1.ErrorWithCause('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 index_js_1.ErrorWithCause(`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 = (0, index_js_3.extractChainQueryContract)({ id: this.chainId }) ??
+            (0, raise_js_1.raise)(new viem_1.MethodNotFoundRpcError(new index_js_1.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 = (0, index_js_3.extractChain)({ id: this.chainId }) ?? (0, raise_js_1.raise)(new index_js_1.UnsupportedChainError());
+        // Convert fee parameters to Circle API fee configuration
+        const fee = await this.parseFeeParams(params);
+        const value = params.value && (0, viem_1.formatEther)((0, viem_1.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 = (0, viem_1.hexToBigInt)(gasLimitHex).toString();
+            return {
+                config: {
+                    gasLimit,
+                    gasPrice: (0, viem_1.formatGwei)((0, viem_1.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 = (0, viem_1.hexToBigInt)(gasLimitHex).toString();
+            return {
+                config: {
+                    gasLimit,
+                    maxFee: maxFeePerGas ? (0, viem_1.formatGwei)((0, viem_1.hexToBigInt)(maxFeePerGas)) : '',
+                    priorityFee: maxPriorityFeePerGas ? (0, viem_1.formatGwei)((0, viem_1.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 ? (0, viem_1.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 index_js_1.ErrorWithCause('Only `latest` block identifier is supported');
+        }
+        const chain = (0, index_js_3.extractChain)({ id: this.chainId }) ?? (0, raise_js_1.raise)(new index_js_1.UnsupportedChainError());
+        const value = params.value && (0, viem_1.formatEther)((0, viem_1.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 (0, viem_1.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 index_js_1.ErrorWithCause(errorDetails, { cause: { code: errorReason, message: errorDetails } });
+                default:
+                    await (0, promises_1.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);
@@ -183,6 +377,9 @@ class Provider extends index_js_2.Provider {
             }
         }
         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 });
@@ -221,6 +418,15 @@ class Provider extends index_js_2.Provider {
         const response = await this.devc.signTypedData(params);
         return response.data;
     }
+    async eth_signTypedData_v4(address, message) {
+        const chain = (0, index_js_3.extractChain)({ id: this.chainId }) ?? (0, raise_js_1.raise)(new index_js_1.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`
@@ -238,6 +444,39 @@ class Provider extends index_js_2.Provider {
         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 = (0, index_js_3.extractChain)({ id: (0, viem_1.hexToNumber)(chainId) }) ?? (0, raise_js_1.raise)(new index_js_1.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 index_js_1.ErrorWithCause('`from` is required');
+        }
+        const blockchain = (0, index_js_3.getBlockchainForSigning)(chain);
+        const wallets = await this.circle_listWallets({
+            address: from,
+            blockchain,
+        });
+        if (wallets.length !== 1) {
+            throw new index_js_1.ErrorWithCause(`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);
@@ -277,6 +516,9 @@ class Provider extends index_js_2.Provider {
             }
         }
         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 });
@@ -297,5 +539,17 @@ class Provider extends index_js_2.Provider {
     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 viem_1.MethodNotFoundRpcError && this.fallback !== undefined) {
+                return this.fallback({ method, params });
+            }
+            throw error;
+        }
+    }
 }
 exports.Provider = Provider;