@turnkey/core 1.11.2 → 1.13.0

package/dist/__clients__/core.mjs

@@ -12,7 +12,20 @@ import { createWalletManager } from '../__wallet__/base.mjs';
 import { toUtf8Bytes } from 'ethers';
 import { verify } from '@turnkey/crypto';
 import { SignatureFormat } from '@turnkey/api-key-stamper';
+import { encodeFunctionData } from 'viem';
 
+const ERC20_TRANSFER_ABI = [
+    {
+        type: "function",
+        name: "transfer",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "to", type: "address" },
+            { name: "amount", type: "uint256" },
+        ],
+        outputs: [{ name: "success", type: "bool" }],
+    },
+];
 class TurnkeyClient {
     constructor(config, 
     // Users can pass in their own stampers, or we will create them. Should we remove this?
@@ -130,7 +143,7 @@ class TurnkeyClient {
          * @throws {TurnkeyError} If there is no active session or if there is an error during the logout process.
          */
         this.logout = async (params) => {
-            withTurnkeyErrorHandling(async () => {
+            return withTurnkeyErrorHandling(async () => {
                 if (params?.sessionKey) {
                     const session = await this.storageManager.getSession(params.sessionKey);
                     this.storageManager.clearSession(params.sessionKey);
@@ -1720,6 +1733,61 @@ class TurnkeyClient {
                 errorCode: TurnkeyErrorCodes.SIGN_AND_SEND_TRANSACTION_ERROR,
             });
         };
+        /**
+         * @beta
+         * * **API subject to change**
+         *
+         * Signs and submits an ERC20 `transfer(address,uint256)` as an Ethereum transaction
+         * using a Turnkey-managed (embedded) wallet.
+         *
+         * This is a convenience wrapper around `ethSendTransaction`:
+         * - Encodes ERC20 transfer calldata.
+         * - Sends a transaction to the token contract.
+         * - Returns a `sendTransactionStatusId` for polling with `pollTransactionStatus`.
+         *
+         * @param params.organizationId - Organization ID to execute the transaction under.
+         *                                Defaults to the active session's organization.
+         * @param params.stampWith - Optional stamper to authorize signing (e.g., passkey).
+         * @param params.transfer - ERC20 transfer parameters.
+         * @returns A promise resolving to the `sendTransactionStatusId`.
+         * @throws {TurnkeyError} If amount encoding fails or Turnkey rejects the transaction.
+         */
+        this.ethSendErc20Transfer = async (params) => {
+            const { organizationId, stampWith = this.config.defaultStamperType, transfer, } = params;
+            const { from, to, tokenAddress, amount, caip2, nonce, gasLimit, maxFeePerGas, maxPriorityFeePerGas, sponsor, } = transfer;
+            return withTurnkeyErrorHandling(async () => {
+                let parsedAmount;
+                try {
+                    parsedAmount = BigInt(amount);
+                }
+                catch {
+                    throw new TurnkeyError("Invalid ERC20 amount. Use a base-unit integer string.", TurnkeyErrorCodes.INVALID_REQUEST);
+                }
+                const data = encodeFunctionData({
+                    abi: ERC20_TRANSFER_ABI,
+                    functionName: "transfer",
+                    args: [to, parsedAmount],
+                });
+                return this.ethSendTransaction({
+                    ...(organizationId !== undefined ? { organizationId } : {}),
+                    ...(stampWith !== undefined ? { stampWith } : {}),
+                    transaction: {
+                        from,
+                        to: tokenAddress,
+                        caip2,
+                        data,
+                        ...(sponsor !== undefined ? { sponsor } : {}),
+                        ...(nonce ? { nonce } : {}),
+                        ...(gasLimit ? { gasLimit } : {}),
+                        ...(maxFeePerGas ? { maxFeePerGas } : {}),
+                        ...(maxPriorityFeePerGas ? { maxPriorityFeePerGas } : {}),
+                    },
+                });
+            }, {
+                errorMessage: "Failed to sign and send ERC20 transfer",
+                errorCode: TurnkeyErrorCodes.ETH_SEND_TRANSACTION_ERROR,
+            });
+        };
         /**
          * @beta
          * * **API subject to change**
@@ -1738,7 +1806,7 @@ class TurnkeyClient {
          *
          * - **Embedded wallets**
          *   - Constructs the payload for Turnkey's `eth_send_transaction` endpoint.
-         *   - Fetches nonces automatically when needed (normal nonce or Gas Station nonce).
+         *   - Forwards transaction fields directly to Turnkey's coordinator.
          *   - Signs and submits the transaction through Turnkey.
          *   - Returns a `sendTransactionStatusId`, which the caller must pass to
          *     `pollTransactionStatus` to obtain the final result (tx hash + status).
@@ -1756,32 +1824,13 @@ class TurnkeyClient {
          */
         this.ethSendTransaction = async (params) => {
             const { organizationId: organizationIdFromParams, stampWith = this.config.defaultStamperType, transaction, } = params;
-            const { from, to, caip2, value, data, nonce, gasLimit, maxFeePerGas, maxPriorityFeePerGas, sponsor, } = transaction;
+            const { from, to, caip2, value, data, nonce, gasLimit, maxFeePerGas, maxPriorityFeePerGas, sponsor, gasStationNonce, } = transaction;
             const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
             const organizationId = organizationIdFromParams || session?.organizationId;
             if (!organizationId) {
                 throw new TurnkeyError("Organization ID must be provided to send a transaction", TurnkeyErrorCodes.INVALID_REQUEST);
             }
             return withTurnkeyErrorHandling(async () => {
-                let gasStationNonce;
-                let fetchedNonce;
-                //
-                // Fetch nonce(s) when needed:
-                // - sponsored: Gas Station nonce
-                // - non-sponsored: regular EIP-1559 nonce
-                //
-                if (!nonce || sponsor) {
-                    const nonceResp = await this.httpClient.getNonces({
-                        organizationId,
-                        address: from,
-                        caip2,
-                        nonce: sponsor ? false : true,
-                        gasStationNonce: sponsor ? true : false,
-                    });
-                    gasStationNonce = nonceResp.gasStationNonce;
-                    fetchedNonce = nonceResp.nonce;
-                }
-                const finalNonce = nonce ?? fetchedNonce;
                 //
                 // Build Turnkey intent
                 //
@@ -1791,15 +1840,14 @@ class TurnkeyClient {
                     caip2,
                     ...(value ? { value } : {}),
                     ...(data ? { data } : {}),
+                    ...(nonce !== undefined ? { nonce } : {}),
                 };
                 if (sponsor) {
                     intent.sponsor = true;
-                    if (gasStationNonce)
+                    if (gasStationNonce !== undefined)
                         intent.gasStationNonce = gasStationNonce;
                 }
                 else {
-                    if (finalNonce !== undefined)
-                        intent.nonce = finalNonce;
                     if (gasLimit)
                         intent.gasLimit = gasLimit;
                     if (maxFeePerGas)
@@ -1824,6 +1872,69 @@ class TurnkeyClient {
                 errorCode: TurnkeyErrorCodes.ETH_SEND_TRANSACTION_ERROR,
             });
         };
+        /**
+         * @beta
+         * * **API subject to change**
+         *
+         * Signs and submits a Solana transaction using a Turnkey-managed (embedded) wallet.
+         *
+         * This method performs **authorization and signing**, and submits the transaction
+         * to Turnkey’s coordinator. It **does not perform any polling** — callers must use
+         * `pollTransactionStatus` to obtain the final on-chain result.
+         *
+         * Behavior:
+         *
+         * - **Connected wallets**
+         *   - Connected wallets are **not supported** by this method.
+         *   - They must instead use `signAndSendTransaction`.
+         *
+         * - **Embedded wallets**
+         *   - Constructs the payload for Turnkey's `sol_send_transaction` endpoint.
+         *   - Signs and submits the transaction through Turnkey.
+         *   - Returns a `sendTransactionStatusId`, which the caller must pass to
+         *     `pollTransactionStatus` to obtain the final result (signature + status).
+         *
+         * @param params.organizationId - Organization ID to execute the transaction under.
+         *                                Defaults to the active session's organization.
+         * @param params.stampWith - Optional stamper to authorize signing (e.g., passkey).
+         * @param params.transaction - The Solana transaction details.
+         * @returns A promise resolving to the `sendTransactionStatusId`.
+         *          This ID must be passed to `pollTransactionStatus`.
+         * @throws {TurnkeyError} If the transaction is invalid or Turnkey rejects it.
+         */
+        this.solSendTransaction = async (params) => {
+            const { organizationId: organizationIdFromParams, stampWith = this.config.defaultStamperType, transaction, } = params;
+            const session = await getActiveSessionOrThrowIfRequired(stampWith, this.storageManager.getActiveSession);
+            const organizationId = organizationIdFromParams || session?.organizationId;
+            if (!organizationId) {
+                throw new TurnkeyError("Organization ID must be provided to send a transaction", TurnkeyErrorCodes.INVALID_REQUEST);
+            }
+            return withTurnkeyErrorHandling(async () => {
+                const intent = {
+                    unsignedTransaction: transaction.unsignedTransaction,
+                    signWith: transaction.signWith,
+                    caip2: transaction.caip2,
+                    ...(transaction.sponsor !== undefined
+                        ? { sponsor: transaction.sponsor }
+                        : {}),
+                    ...(transaction.recentBlockhash
+                        ? { recentBlockhash: transaction.recentBlockhash }
+                        : {}),
+                };
+                const resp = await this.httpClient.solSendTransaction({
+                    ...intent,
+                    organizationId,
+                }, stampWith);
+                const id = resp.sendTransactionStatusId;
+                if (!id) {
+                    throw new TurnkeyError("Missing sendTransactionStatusId", TurnkeyErrorCodes.SOL_SEND_TRANSACTION_ERROR);
+                }
+                return id;
+            }, {
+                errorMessage: "Failed to sign and send Solana transaction",
+                errorCode: TurnkeyErrorCodes.SOL_SEND_TRANSACTION_ERROR,
+            });
+        };
         /**
          * Fetches the user details for the current session or a specified user.
          *
@@ -2835,7 +2946,7 @@ class TurnkeyClient {
             const { sessionToken, sessionKey = SessionKey.DefaultSessionkey } = params;
             if (!sessionToken)
                 return;
-            withTurnkeyErrorHandling(async () => {
+            return withTurnkeyErrorHandling(async () => {
                 await this.storageManager.storeSession(sessionToken, sessionKey);
             }, {
                 errorMessage: "Failed to store session",
@@ -2858,7 +2969,7 @@ class TurnkeyClient {
          */
         this.clearSession = async (params) => {
             const { sessionKey = SessionKey.DefaultSessionkey } = params || {};
-            withTurnkeyErrorHandling(async () => {
+            return withTurnkeyErrorHandling(async () => {
                 const session = await this.storageManager.getSession(sessionKey);
                 if (session) {
                     await Promise.all([
@@ -2886,7 +2997,7 @@ class TurnkeyClient {
          * @throws {TurnkeyError} If no sessions exist or if there is an error clearing all sessions.
          */
         this.clearAllSessions = async () => {
-            withTurnkeyErrorHandling(async () => {
+            return withTurnkeyErrorHandling(async () => {
                 const sessionKeys = await this.storageManager.listSessionKeys();
                 if (sessionKeys.length === 0)
                     return;
@@ -3056,7 +3167,7 @@ class TurnkeyClient {
          * @throws {TurnkeyError} If there is an error listing, checking, or deleting unused key pairs.
          */
         this.clearUnusedKeyPairs = async () => {
-            withTurnkeyErrorHandling(async () => {
+            return withTurnkeyErrorHandling(async () => {
                 const publicKeys = await this.apiKeyStamper?.listKeyPairs();
                 if (!publicKeys || publicKeys.length === 0) {
                     return;
@@ -3265,26 +3376,28 @@ class TurnkeyClient {
      * @beta
      * **API subject to change**
      *
-     * Polls Turnkey for the final result of a previously submitted Ethereum transaction.
+     * Polls Turnkey for the final result of a previously submitted transaction.
      *
      * This function repeatedly calls `getSendTransactionStatus` until the transaction
      * reaches a terminal state.
      *
      * Terminal states:
-     * - **COMPLETED** or **INCLUDED** → resolves with `{ txHash }`
+     * - **COMPLETED** or **INCLUDED** → resolves with chain-specific transaction details
      * - **FAILED** rejects with an error
      *
      * Behavior:
      *
      * - Queries Turnkey every 500ms.
      * - Stops polling automatically when a terminal state is reached.
-     * - Extracts the canonical on-chain hash via `resp.eth.txHash` when available.
+     * - Returns the full status payload from Turnkey.
+     * - When available, Ethereum transaction details are exposed at `resp.eth.txHash`.
      *
-     * @param organizationId - Organization ID under which the transaction was submitted.
-     * @param sendTransactionStatusId - Status ID returned by `ethSendTransaction.
-     * @param pollingIntervalMs - Optional polling interval in milliseconds (default: 500ms).
+     * @param params.organizationId - Organization ID under which the transaction was submitted.
+     * @param params.sendTransactionStatusId - Status ID returned by `ethSendTransaction` or `solSendTransaction`.
+     * @param params.pollingIntervalMs - Optional polling interval in milliseconds (default: 500ms).
+     * @param params.stampWith - Optional stamper to use for polling.
      *
-     * @returns A promise resolving to `{ txHash?: string }` if successful.
+     * @returns A promise resolving to the transaction status payload if successful.
      * @throws {Error | string} If the transaction fails or is cancelled.
      */
     async pollTransactionStatus(params) {