thirdweb 5.97.1 → 5.97.3

package/src/engine/get-status.ts

@@ -0,0 +1,180 @@
+import { searchTransactions } from "@thirdweb-dev/engine";
+import type { Chain } from "../chains/types.js";
+import { getCachedChain } from "../chains/utils.js";
+import type { ThirdwebClient } from "../client/client.js";
+import type { WaitForReceiptOptions } from "../transaction/actions/wait-for-tx-receipt.js";
+import { getThirdwebBaseUrl } from "../utils/domains.js";
+import type { Hex } from "../utils/encoding/hex.js";
+import { getClientFetch } from "../utils/fetch.js";
+import { stringify } from "../utils/json.js";
+import type { Prettify } from "../utils/type-utils.js";
+
+export type RevertData = {
+  errorName: string;
+  errorArgs: Record<string, unknown>;
+};
+
+type ExecutionResult4337Serialized =
+  | {
+      status: "QUEUED";
+    }
+  | {
+      status: "FAILED";
+      error: string;
+    }
+  | {
+      status: "SUBMITTED";
+      monitoringStatus: "WILL_MONITOR" | "CANNOT_MONITOR";
+      userOpHash: string;
+    }
+  | ({
+      status: "CONFIRMED";
+      userOpHash: Hex;
+      transactionHash: Hex;
+      actualGasCost: string;
+      actualGasUsed: string;
+      nonce: string;
+    } & (
+      | {
+          onchainStatus: "SUCCESS";
+        }
+      | {
+          onchainStatus: "REVERTED";
+          revertData?: RevertData;
+        }
+    ));
+
+export type ExecutionResult = Prettify<
+  ExecutionResult4337Serialized & {
+    chain: Chain;
+    from: string | undefined;
+    id: string;
+  }
+>;
+
+/**
+ * Get the execution status of a transaction.
+ * @param args - The arguments for the transaction.
+ * @param args.client - The thirdweb client to use.
+ * @param args.transactionId - The id of the transaction to get the status of.
+ * @engine
+ * @example
+ * ```ts
+ * import { Engine } from "thirdweb";
+ *
+ * const executionResult = await Engine.getTransactionStatus({
+ *   client,
+ *   transactionId,
+ * });
+ * console.log(executionResult.status);
+ * ```
+ */
+export async function getTransactionStatus(args: {
+  client: ThirdwebClient;
+  transactionId: string;
+}): Promise<ExecutionResult> {
+  const { client, transactionId } = args;
+  const searchResult = await searchTransactions({
+    baseUrl: getThirdwebBaseUrl("engineCloud"),
+    fetch: getClientFetch(client),
+    body: {
+      filters: [
+        {
+          field: "id",
+          values: [transactionId],
+          operation: "OR",
+        },
+      ],
+    },
+  });
+
+  if (searchResult.error) {
+    throw new Error(
+      `Error searching for transaction ${transactionId}: ${stringify(
+        searchResult.error,
+      )}`,
+    );
+  }
+
+  const data = searchResult.data?.result?.transactions?.[0];
+
+  if (!data) {
+    throw new Error(`Transaction ${transactionId} not found`);
+  }
+
+  const executionResult = data.executionResult as ExecutionResult4337Serialized;
+  return {
+    ...executionResult,
+    chain: getCachedChain(Number(data.chainId)),
+    from: data.from ?? undefined,
+    id: data.id,
+  };
+}
+
+/**
+ * Wait for a transaction to be submitted onchain and return the transaction hash.
+ * @param args - The arguments for the transaction.
+ * @param args.client - The thirdweb client to use.
+ * @param args.transactionId - The id of the transaction to wait for.
+ * @param args.timeoutInSeconds - The timeout in seconds.
+ * @engine
+ * @example
+ * ```ts
+ * import { Engine } from "thirdweb";
+ *
+ * const { transactionHash } = await Engine.waitForTransactionHash({
+ *   client,
+ *   transactionId, // the transaction id returned from enqueueTransaction
+ * });
+ * ```
+ */
+export async function waitForTransactionHash(args: {
+  client: ThirdwebClient;
+  transactionId: string;
+  timeoutInSeconds?: number;
+}): Promise<WaitForReceiptOptions> {
+  const startTime = Date.now();
+  const TIMEOUT_IN_MS = args.timeoutInSeconds
+    ? args.timeoutInSeconds * 1000
+    : 5 * 60 * 1000; // 5 minutes in milliseconds
+
+  while (Date.now() - startTime < TIMEOUT_IN_MS) {
+    const executionResult = await getTransactionStatus(args);
+    const status = executionResult.status;
+
+    switch (status) {
+      case "FAILED": {
+        throw new Error(
+          `Transaction failed: ${executionResult.error || "Unknown error"}`,
+        );
+      }
+      case "CONFIRMED": {
+        const onchainStatus =
+          executionResult && "onchainStatus" in executionResult
+            ? executionResult.onchainStatus
+            : null;
+        if (onchainStatus === "REVERTED") {
+          const revertData =
+            "revertData" in executionResult
+              ? executionResult.revertData
+              : undefined;
+          throw new Error(
+            `Transaction reverted: ${revertData?.errorName || ""} ${revertData?.errorArgs ? stringify(revertData.errorArgs) : ""}`,
+          );
+        }
+        return {
+          transactionHash: executionResult.transactionHash as Hex,
+          client: args.client,
+          chain: executionResult.chain,
+        };
+      }
+      default: {
+        // wait for the transaction to be confirmed
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+      }
+    }
+  }
+  throw new Error(
+    `Transaction timed out after ${TIMEOUT_IN_MS / 1000} seconds`,
+  );
+}

package/src/engine/index.ts

@@ -0,0 +1,11 @@
+export {
+  serverWallet,
+  type ServerWalletOptions,
+  type ServerWallet,
+} from "./server-wallet.js";
+export {
+  getTransactionStatus,
+  waitForTransactionHash,
+  type ExecutionResult,
+  type RevertData,
+} from "./get-status.js";

package/src/engine/server-wallet.test.ts

@@ -0,0 +1,196 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { TEST_CLIENT } from "../../test/src/test-clients.js";
+import { TEST_ACCOUNT_B } from "../../test/src/test-wallets.js";
+import { typedData } from "../../test/src/typed-data.js";
+import { arbitrumSepolia } from "../chains/chain-definitions/arbitrum-sepolia.js";
+import { sepolia } from "../chains/chain-definitions/sepolia.js";
+import { getContract } from "../contract/contract.js";
+import { setContractURI } from "../extensions/common/__generated__/IContractMetadata/write/setContractURI.js";
+import { claimTo } from "../extensions/erc1155/drops/write/claimTo.js";
+import { getAllActiveSigners } from "../extensions/erc4337/__generated__/IAccountPermissions/read/getAllActiveSigners.js";
+import { sendTransaction } from "../transaction/actions/send-transaction.js";
+import { setThirdwebDomains } from "../utils/domains.js";
+import {
+  DEFAULT_ACCOUNT_FACTORY_V0_6,
+  ENTRYPOINT_ADDRESS_v0_6,
+} from "../wallets/smart/lib/constants.js";
+import { smartWallet } from "../wallets/smart/smart-wallet.js";
+import { generateAccount } from "../wallets/utils/generateAccount.js";
+import * as Engine from "./index.js";
+
+describe.runIf(
+  process.env.TW_SECRET_KEY &&
+    process.env.VAULT_TOKEN &&
+    process.env.ENGINE_CLOUD_WALLET_ADDRESS &&
+    process.env.ENGINE_CLOUD_WALLET_ADDRESS_EOA,
+)(
+  "Engine Cloud",
+  {
+    retry: 0,
+  },
+  () => {
+    let serverWallet: Engine.ServerWallet;
+
+    beforeAll(async () => {
+      setThirdwebDomains({
+        rpc: "rpc.thirdweb-dev.com",
+        storage: "storage.thirdweb-dev.com",
+        bundler: "bundler.thirdweb-dev.com",
+        engineCloud: "engine.thirdweb-dev.com",
+      });
+      serverWallet = Engine.serverWallet({
+        client: TEST_CLIENT,
+        vaultAccessToken: process.env.VAULT_TOKEN as string,
+        address: process.env.ENGINE_CLOUD_WALLET_ADDRESS as string,
+        chain: arbitrumSepolia,
+      });
+    });
+
+    it("should sign a message", async () => {
+      const signature = await serverWallet.signMessage({
+        message: "hello",
+      });
+      expect(signature).toBeDefined();
+    });
+
+    it("should sign typed data", async () => {
+      const signature = await serverWallet.signTypedData({
+        ...typedData.basic,
+      });
+      expect(signature).toBeDefined();
+    });
+
+    it("should send a tx with regular API", async () => {
+      const tx = await sendTransaction({
+        account: serverWallet,
+        transaction: {
+          client: TEST_CLIENT,
+          chain: arbitrumSepolia,
+          to: TEST_ACCOUNT_B.address,
+          value: 0n,
+        },
+      });
+      expect(tx).toBeDefined();
+    });
+
+    it("should enqueue a tx", async () => {
+      const nftContract = getContract({
+        client: TEST_CLIENT,
+        chain: sepolia,
+        address: "0xe2cb0eb5147b42095c2FfA6F7ec953bb0bE347D8",
+      });
+      const claimTx = claimTo({
+        contract: nftContract,
+        to: TEST_ACCOUNT_B.address,
+        tokenId: 0n,
+        quantity: 1n,
+      });
+      const result = await serverWallet.enqueueTransaction({
+        transaction: claimTx,
+      });
+      expect(result.transactionId).toBeDefined();
+      const txHash = await Engine.waitForTransactionHash({
+        client: TEST_CLIENT,
+        transactionId: result.transactionId,
+      });
+      expect(txHash.transactionHash).toBeDefined();
+    });
+
+    it("should send a extension tx", async () => {
+      const nftContract = getContract({
+        client: TEST_CLIENT,
+        chain: sepolia,
+        address: "0xe2cb0eb5147b42095c2FfA6F7ec953bb0bE347D8",
+      });
+      const claimTx = claimTo({
+        contract: nftContract,
+        to: TEST_ACCOUNT_B.address,
+        tokenId: 0n,
+        quantity: 1n,
+      });
+      const tx = await sendTransaction({
+        account: serverWallet,
+        transaction: claimTx,
+      });
+      expect(tx).toBeDefined();
+    });
+
+    it("should get revert reason", async () => {
+      const nftContract = getContract({
+        client: TEST_CLIENT,
+        chain: sepolia,
+        address: "0xe2cb0eb5147b42095c2FfA6F7ec953bb0bE347D8",
+      });
+      const transaction = setContractURI({
+        contract: nftContract,
+        uri: "https://example.com",
+        overrides: {
+          gas: 1000000n, // skip simulation
+        },
+      });
+      await expect(
+        sendTransaction({
+          account: serverWallet,
+          transaction,
+        }),
+      ).rejects.toThrow();
+    });
+
+    it("should send a session key tx", async () => {
+      const sessionKeyAccountAddress = process.env
+        .ENGINE_CLOUD_WALLET_ADDRESS_EOA as string;
+      const personalAccount = await generateAccount({
+        client: TEST_CLIENT,
+      });
+      const smart = smartWallet({
+        chain: sepolia,
+        sponsorGas: true,
+        sessionKey: {
+          address: sessionKeyAccountAddress,
+          permissions: {
+            approvedTargets: "*",
+          },
+        },
+      });
+      const smartAccount = await smart.connect({
+        client: TEST_CLIENT,
+        personalAccount,
+      });
+      expect(smartAccount.address).toBeDefined();
+
+      const signers = await getAllActiveSigners({
+        contract: getContract({
+          client: TEST_CLIENT,
+          chain: sepolia,
+          address: smartAccount.address,
+        }),
+      });
+      expect(signers.map((s) => s.signer)).toContain(sessionKeyAccountAddress);
+
+      const serverWallet = Engine.serverWallet({
+        client: TEST_CLIENT,
+        vaultAccessToken: process.env.VAULT_TOKEN as string,
+        address: sessionKeyAccountAddress,
+        chain: sepolia,
+        executionOptions: {
+          type: "ERC4337",
+          signerAddress: sessionKeyAccountAddress,
+          smartAccountAddress: smartAccount.address,
+          factoryAddress: DEFAULT_ACCOUNT_FACTORY_V0_6,
+          entrypointAddress: ENTRYPOINT_ADDRESS_v0_6,
+        },
+      });
+
+      const tx = await sendTransaction({
+        account: serverWallet,
+        transaction: {
+          client: TEST_CLIENT,
+          chain: sepolia,
+          to: TEST_ACCOUNT_B.address,
+          value: 0n,
+        },
+      });
+      expect(tx).toBeDefined();
+    });
+  },
+);

package/src/engine/server-wallet.ts

@@ -0,0 +1,284 @@
+import {
+  type AaExecutionOptions,
+  type AaZksyncExecutionOptions,
+  sendTransaction,
+  signMessage,
+  signTypedData,
+} from "@thirdweb-dev/engine";
+import type { Chain } from "../chains/types.js";
+import type { ThirdwebClient } from "../client/client.js";
+import { encode } from "../transaction/actions/encode.js";
+import { toSerializableTransaction } from "../transaction/actions/to-serializable-transaction.js";
+import type { PreparedTransaction } from "../transaction/prepare-transaction.js";
+import { getThirdwebBaseUrl } from "../utils/domains.js";
+import { type Hex, toHex } from "../utils/encoding/hex.js";
+import { getClientFetch } from "../utils/fetch.js";
+import { stringify } from "../utils/json.js";
+import { resolvePromisedValue } from "../utils/promise/resolve-promised-value.js";
+import type {
+  Account,
+  SendTransactionOption,
+} from "../wallets/interfaces/wallet.js";
+import { waitForTransactionHash } from "./get-status.js";
+
+/**
+ * Options for creating an server wallet.
+ */
+export type ServerWalletOptions = {
+  /**
+   * The thirdweb client to use for authentication to thirdweb services.
+   */
+  client: ThirdwebClient;
+  /**
+   * The vault access token to use your server wallet.
+   */
+  vaultAccessToken: string;
+  /**
+   * The server wallet address to use for sending transactions inside engine.
+   */
+  address: string;
+  /**
+   * The chain to use for signing messages and typed data (smart server wallet only).
+   */
+  chain?: Chain;
+  /**
+   * Optional custom execution options to use for sending transactions and signing data.
+   */
+  executionOptions?:
+    | Omit<AaExecutionOptions, "chainId">
+    | Omit<AaZksyncExecutionOptions, "chainId">;
+};
+
+export type ServerWallet = Account & {
+  enqueueTransaction: (args: {
+    transaction: PreparedTransaction;
+    simulate?: boolean;
+  }) => Promise<{ transactionId: string }>;
+};
+
+/**
+ * Create a server wallet for sending transactions and signing messages via engine (v3+).
+ * @param options - The server wallet options.
+ * @returns An account object that can be used to send transactions and sign messages.
+ * @engine
+ * @example
+ * ### Creating a server wallet
+ * ```ts
+ * import { Engine } from "thirdweb";
+ *
+ * const client = createThirdwebClient({
+ *   secretKey: "<your-project-secret-key>",
+ * });
+ *
+ * const myServerWallet = Engine.serverWallet({
+ *   client,
+ *   address: "<your-server-wallet-address>",
+ *   vaultAccessToken: "<your-vault-access-token>",
+ * });
+ * ```
+ *
+ * ### Sending a transaction
+ * ```ts
+ * // prepare the transaction
+ * const transaction = claimTo({
+ *   contract,
+ *   to: "0x...",
+ *   quantity: 1n,
+ * });
+ *
+ * // enqueue the transaction
+ * const { transactionId } = await myServerWallet.enqueueTransaction({
+ *   transaction,
+ * });
+ * ```
+ *
+ * ### Polling for the transaction to be submitted onchain
+ * ```ts
+ * // optionally poll for the transaction to be submitted onchain
+ * const { transactionHash } = await Engine.waitForTransactionHash({
+ *   client,
+ *   transactionId,
+ * });
+ * console.log("Transaction sent:", transactionHash);
+ * ```
+ *
+ * ### Getting the execution status of a transaction
+ * ```ts
+ * const executionResult = await Engine.getTransactionStatus({
+ *   client,
+ *   transactionId,
+ * });
+ * console.log("Transaction status:", executionResult.status);
+ * ```
+ */
+export function serverWallet(options: ServerWalletOptions): ServerWallet {
+  const { client, vaultAccessToken, address, chain, executionOptions } =
+    options;
+  const headers: HeadersInit = {
+    "x-vault-access-token": vaultAccessToken,
+  };
+
+  const getExecutionOptions = (chainId: number) => {
+    return executionOptions
+      ? {
+          ...executionOptions,
+          chainId: chainId.toString(),
+        }
+      : {
+          from: address,
+          chainId: chainId.toString(),
+        };
+  };
+
+  const enqueueTx = async (transaction: SendTransactionOption) => {
+    const body = {
+      executionOptions: getExecutionOptions(transaction.chainId),
+      params: [
+        {
+          to: transaction.to ?? undefined,
+          data: transaction.data,
+          value: transaction.value?.toString(),
+        },
+      ],
+    };
+
+    const result = await sendTransaction({
+      baseUrl: getThirdwebBaseUrl("engineCloud"),
+      fetch: getClientFetch(client),
+      headers,
+      body,
+    });
+
+    if (result.error) {
+      throw new Error(`Error sending transaction: ${result.error}`);
+    }
+
+    const data = result.data?.result;
+    if (!data) {
+      throw new Error("No data returned from engine");
+    }
+    const transactionId = data.transactions?.[0]?.id;
+    if (!transactionId) {
+      throw new Error("No transactionId returned from engine");
+    }
+    return transactionId;
+  };
+
+  return {
+    address,
+    enqueueTransaction: async (args: {
+      transaction: PreparedTransaction;
+      simulate?: boolean;
+    }) => {
+      let serializedTransaction: SendTransactionOption;
+      if (args.simulate) {
+        serializedTransaction = await toSerializableTransaction({
+          transaction: args.transaction,
+        });
+      } else {
+        const [to, data, value] = await Promise.all([
+          args.transaction.to
+            ? resolvePromisedValue(args.transaction.to)
+            : null,
+          encode(args.transaction),
+          args.transaction.value
+            ? resolvePromisedValue(args.transaction.value)
+            : null,
+        ]);
+        serializedTransaction = {
+          chainId: args.transaction.chain.id,
+          data,
+          to: to ?? undefined,
+          value: value ?? undefined,
+        };
+      }
+      const transactionId = await enqueueTx(serializedTransaction);
+      return { transactionId };
+    },
+    sendTransaction: async (transaction: SendTransactionOption) => {
+      const transactionId = await enqueueTx(transaction);
+      return waitForTransactionHash({
+        client,
+        transactionId,
+      });
+    },
+    signMessage: async (data) => {
+      const { message, chainId } = data;
+      let engineMessage: string | Hex;
+      let isBytes = false;
+      if (typeof message === "string") {
+        engineMessage = message;
+      } else {
+        engineMessage = toHex(message.raw);
+        isBytes = true;
+      }
+
+      const signingChainId = chainId || chain?.id;
+      if (!signingChainId) {
+        throw new Error("Chain ID is required for signing messages");
+      }
+
+      const signResult = await signMessage({
+        baseUrl: getThirdwebBaseUrl("engineCloud"),
+        fetch: getClientFetch(client),
+        headers,
+        body: {
+          executionOptions: getExecutionOptions(signingChainId),
+          params: [
+            {
+              message: engineMessage,
+              messageFormat: isBytes ? "hex" : "text",
+            },
+          ],
+        },
+      });
+
+      if (signResult.error) {
+        throw new Error(
+          `Error signing message: ${stringify(signResult.error)}`,
+        );
+      }
+
+      const signatureResult = signResult.data?.result.results[0];
+      if (signatureResult?.success) {
+        return signatureResult.result.signature as Hex;
+      }
+
+      throw new Error(
+        `Failed to sign message: ${signatureResult?.error?.message || "Unknown error"}`,
+      );
+    },
+    signTypedData: async (typedData) => {
+      const signingChainId = chain?.id;
+      if (!signingChainId) {
+        throw new Error("Chain ID is required for signing messages");
+      }
+
+      const signResult = await signTypedData({
+        baseUrl: getThirdwebBaseUrl("engineCloud"),
+        fetch: getClientFetch(client),
+        headers,
+        body: {
+          executionOptions: getExecutionOptions(signingChainId),
+          // biome-ignore lint/suspicious/noExplicitAny: TODO: fix ts / hey-api type clash
+          params: [typedData as any],
+        },
+      });
+
+      if (signResult.error) {
+        throw new Error(
+          `Error signing message: ${stringify(signResult.error)}`,
+        );
+      }
+
+      const signatureResult = signResult.data?.result.results[0];
+      if (signatureResult?.success) {
+        return signatureResult.result.signature as Hex;
+      }
+
+      throw new Error(
+        `Failed to sign message: ${signatureResult?.error?.message || "Unknown error"}`,
+      );
+    },
+  };
+}

package/src/exports/engine.ts

@@ -0,0 +1 @@
+export * from "../engine/index.js";

package/src/exports/thirdweb.ts

@@ -81,6 +81,11 @@ export * as Bridge from "../bridge/index.js";
  */
 export * as Insight from "../insight/index.js";
 
+/**
+ * ENGINE
+ */
+export * as Engine from "../engine/index.js";
+
 /**
  * WALLETS
  */

package/src/extensions/erc721/read/getNFT.test.ts

@@ -58,7 +58,7 @@ describe.runIf(process.env.TW_SECRET_KEY)("erc721.getNFT", () => {
       includeOwner: true,
     });
     expect(nft.metadata.name).toBe("Doodle #1");
-    expect(nft.owner).toBe("0xbE9936FCFC50666f5425FDE4A9decC59cEF73b24");
+    expect(nft.owner).toBeDefined();
     expect(nft).toMatchInlineSnapshot(`
       {
         "chainId": 1,
@@ -92,7 +92,7 @@ describe.runIf(process.env.TW_SECRET_KEY)("erc721.getNFT", () => {
           "name": "Doodle #1",
           "uri": "ipfs://QmPMc4tcBsMqLRuCQtPmPe84bpSjrC3Ky7t3JWuHXYB4aS/1",
         },
-        "owner": "0xbE9936FCFC50666f5425FDE4A9decC59cEF73b24",
+        "owner": "0x620b70123fB810F6C653DA7644b5dD0b6312e4D8",
         "tokenAddress": "0x8a90cab2b38dba80c64b7734e58ee1db38b8992e",
         "tokenURI": "ipfs://QmPMc4tcBsMqLRuCQtPmPe84bpSjrC3Ky7t3JWuHXYB4aS/1",
         "type": "ERC721",