feat(transactions): add support for gasless transactions (#2818)

Co-authored-by: Joaquim Verges <joaquim.verges@gmail.com>

Author: jnsdls

.changeset/grumpy-kangaroos-relax.md

@@ -0,0 +1,36 @@
+---
+"thirdweb": minor
+---
+
+**Gasless transactions in Typescript**
+
+```ts
+import { sendTransaction } from "thirdweb";
+
+const result = sendTransaction({
+  transaction,
+  account,
+  gasless: {
+    provider: "engine",
+    relayerUrl: "https://...",
+    relayerForwarderAddress: "0x...",
+  },
+});
+```
+
+**Gasless transactions in React**
+
+```jsx
+import { useSendTransaction } from "thirdweb/react";
+
+const { mutate } = useSendTransaction({
+  gasless: {
+    provider: "engine",
+    relayerUrl: "https://...",
+    relayerForwarderAddress: "0x...",
+  },
+});
+
+// Call mutate with the transaction object
+mutate(transaction);
+```

.vscode/settings.json

@@ -8,5 +8,8 @@
   "typescript.preferences.importModuleSpecifier": "relative",
   "[typescriptreact]": {
     "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[markdown]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
   }
 }

packages/thirdweb/src/react/core/hooks/contract/useSendTransaction.ts

@@ -1,5 +1,6 @@
 import { type UseMutationResult, useMutation } from "@tanstack/react-query";
 import { estimateGasCost } from "../../../../transaction/actions/estimate-gas-cost.js";
+import type { GaslessOptions } from "../../../../transaction/actions/gasless/types.js";
 import { sendTransaction } from "../../../../transaction/actions/send-transaction.js";
 import type { WaitForReceiptOptions } from "../../../../transaction/actions/wait-for-tx-receipt.js";
 import type { PreparedTransaction } from "../../../../transaction/prepare-transaction.js";
@@ -34,6 +35,7 @@ type ShowModalData = {
  */
 export function useSendTransactionCore(
   showPayModal?: (data: ShowModalData) => void,
+  gasless?: GaslessOptions,
 ): UseMutationResult<WaitForReceiptOptions, Error, PreparedTransaction> {
   const account = useActiveAccount();
 
@@ -47,6 +49,7 @@ export function useSendTransactionCore(
         return sendTransaction({
           transaction: tx,
           account,
+          gasless,
         });
       }
 
@@ -56,6 +59,7 @@ export function useSendTransactionCore(
             const res = await sendTransaction({
               transaction: tx,
               account,
+              gasless,
             });
 
             resolve(res);

packages/thirdweb/src/react/core/hooks/wallets/wallet-hooks.tsx

@@ -171,13 +171,14 @@ export function useConnect() {
  * Disconnect from given account
  * @example
  * ```jsx
- * import { useDisconnect } from "thirdweb/react";
+ * import { useDisconnect, useActiveWallet } from "thirdweb/react";
  *
  * function Example() {
  *   const { disconnect } = useDisconnect();
+ *   const wallet = useActiveWallet();
  *
  *   return (
- *     <button onClick={() => disconnect(account)}>
+ *     <button onClick={() => disconnect(wallet)}>
  *       Disconnect
  *     </button>
  *   );

packages/thirdweb/src/react/web/hooks/useSendTransaction.tsx

@@ -1,5 +1,6 @@
 import { useContext, useState } from "react";
 import type { ThirdwebClient } from "../../../client/client.js";
+import type { GaslessOptions } from "../../../transaction/actions/gasless/types.js";
 import type { PreparedTransaction } from "../../../transaction/prepare-transaction.js";
 import { useSendTransactionCore } from "../../core/hooks/contract/useSendTransaction.js";
 import { SetRootElementContext } from "../../core/providers/RootElementContext.js";
@@ -47,6 +48,12 @@ export type SendTransactionConfig = {
         theme?: Theme | "light" | "dark";
       }
     | false;
+
+  /**
+   * Configuration for gasless transactions.
+   * Refer to [`GaslessOptions`](https://portal.thirdweb.com/references/typescript/v5/GaslessOptions) for more details.
+   */
+  gasless?: GaslessOptions;
 };
 
 /**
@@ -91,6 +98,7 @@ export function useSendTransaction(config: SendTransactionConfig = {}) {
             />,
           );
         },
+    config.gasless,
   );
 }
 

packages/thirdweb/src/transaction/actions/gasless/providers/biconomy.test.ts

@@ -0,0 +1,82 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { FORKED_ETHEREUM_CHAIN_WITH_MINING } from "../../../../../test/src/chains.js";
+import { TEST_CLIENT } from "../../../../../test/src/test-clients.js";
+import {
+  TEST_ACCOUNT_A,
+  TEST_ACCOUNT_B,
+} from "../../../../../test/src/test-wallets.js";
+import {
+  type ThirdwebContract,
+  getContract,
+} from "../../../../contract/contract.js";
+import { mintTo } from "../../../../extensions/erc20/write/mintTo.js";
+import { transfer } from "../../../../extensions/erc20/write/transfer.js";
+import { deployERC20Contract } from "../../../../extensions/prebuilts/deploy-erc20.js";
+import { isHex } from "../../../../utils/encoding/hex.js";
+import { sendAndConfirmTransaction } from "../../send-and-confirm-transaction.js";
+import { toSerializableTransaction } from "../../to-serializable-transaction.js";
+import { prepareBiconomyTransaction } from "./biconomy.js";
+
+describe.runIf(process.env.TW_SECRET_KEY)("prepareBiconomyTransaction", () => {
+  let erc20Contract: ThirdwebContract;
+  beforeAll(async () => {
+    erc20Contract = getContract({
+      address: await deployERC20Contract({
+        account: TEST_ACCOUNT_A,
+        chain: FORKED_ETHEREUM_CHAIN_WITH_MINING,
+        client: TEST_CLIENT,
+        params: { name: "Test Token", symbol: "TST" },
+        type: "TokenERC20",
+      }),
+      chain: FORKED_ETHEREUM_CHAIN_WITH_MINING,
+      client: TEST_CLIENT,
+    });
+    // mint some tokens to the account
+    await sendAndConfirmTransaction({
+      transaction: mintTo({
+        contract: erc20Contract,
+        amount: "1000",
+        to: TEST_ACCOUNT_A.address,
+      }),
+      account: TEST_ACCOUNT_A,
+    });
+  }, 60_000);
+  it("should prepare a Biconomy transaction", async () => {
+    const transaction = transfer({
+      amount: "100",
+      contract: erc20Contract,
+      to: TEST_ACCOUNT_B.address,
+    });
+
+    // seralizable transaction
+    const serializableTransaction = await toSerializableTransaction({
+      transaction,
+      from: TEST_ACCOUNT_A.address,
+    });
+
+    const result = await prepareBiconomyTransaction({
+      account: TEST_ACCOUNT_A,
+      serializableTransaction,
+      transaction,
+      gasless: {
+        apiId: "TEST_ID",
+        apiKey: "TEST_KEY",
+        // mainnet forwarder address
+        relayerForwarderAddress: "0x84a0856b038eaAd1cC7E297cF34A7e72685A8693",
+        provider: "biconomy",
+      },
+    });
+
+    const [request, signature] = result;
+
+    expect(isHex(signature)).toBe(true);
+    expect(request.batchId).toBe(0n);
+    expect(request.batchNonce).toBe(0n);
+    expect(request.data).toMatchInlineSnapshot(
+      `"0xa9059cbb00000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c80000000000000000000000000000000000000000000000056bc75e2d63100000"`,
+    );
+    expect(request.deadline).toBeGreaterThan(0);
+    expect(request.from).toBe(TEST_ACCOUNT_A.address);
+    expect(request.to).toBe(erc20Contract.address);
+  });
+});

packages/thirdweb/src/transaction/actions/gasless/providers/biconomy.ts

@@ -0,0 +1,150 @@
+import type { Address } from "abitype";
+import { type TransactionSerializable, encodeAbiParameters } from "viem";
+import { ADDRESS_ZERO } from "../../../../constants/addresses.js";
+import { getContract } from "../../../../contract/contract.js";
+import { isHex } from "../../../../utils/encoding/helpers/is-hex.js";
+import { keccak256 } from "../../../../utils/hashing/keccak256.js";
+import { stringify } from "../../../../utils/json.js";
+import type { Account } from "../../../../wallets/interfaces/wallet.js";
+import type { PreparedTransaction } from "../../../prepare-transaction.js";
+import { readContract } from "../../../read-contract.js";
+import type { WaitForReceiptOptions } from "../../wait-for-tx-receipt.js";
+
+export type BiconomyOptions = {
+  provider: "biconomy";
+  // you can find the correct forwarder for your network here: https://docs-gasless.biconomy.io/misc/contract-addresses
+  relayerForwarderAddress: Address;
+  apiId: string;
+  apiKey: string;
+  deadlineSeconds?: number; // default: 3600
+};
+
+type SendBiconomyTransactionOptions = {
+  account: Account;
+  // TODO: update this to `Transaction<"prepared">` once the type is available to ensure only prepared transactions are accepted
+  // biome-ignore lint/suspicious/noExplicitAny: library function that accepts any prepared transaction type
+  transaction: PreparedTransaction<any>;
+  serializableTransaction: TransactionSerializable;
+  gasless: BiconomyOptions;
+};
+
+// we do not send multiple batches so this stays consistent
+const BATCH_ID = 0n;
+
+/**
+ * @internal - only exported for testing
+ */
+export async function prepareBiconomyTransaction({
+  account,
+  serializableTransaction,
+  transaction,
+  gasless,
+}: SendBiconomyTransactionOptions) {
+  const forwarderContract = getContract({
+    address: gasless.relayerForwarderAddress,
+    chain: transaction.chain,
+    client: transaction.client,
+  });
+
+  // get the nonce
+  const nonce = await readContract({
+    contract: forwarderContract,
+    method: "function getNonce(address,uint256) view returns (uint256)",
+    params: [account.address, BATCH_ID],
+  });
+
+  const deadline =
+    Math.floor(Date.now() / 1000) + (gasless.deadlineSeconds ?? 3600);
+
+  const request = {
+    from: account.address,
+    to: serializableTransaction.to,
+    token: ADDRESS_ZERO,
+    txGas: serializableTransaction.gas,
+    tokenGasPrice: 0n,
+    batchId: BATCH_ID,
+    batchNonce: nonce,
+    deadline: deadline,
+    data: serializableTransaction.data,
+  };
+
+  if (!request.to) {
+    throw new Error("Cannot send a transaction without a `to` address");
+  }
+  if (!request.txGas) {
+    throw new Error("Cannot send a transaction without a `gas` value");
+  }
+  if (!request.data) {
+    throw new Error("Cannot send a transaction without a `data` value");
+  }
+
+  // create the hash
+  const message = encodeAbiParameters(
+    [
+      { type: "address" },
+      { type: "address" },
+      { type: "address" },
+      { type: "uint256" },
+      { type: "uint256" },
+      { type: "uint256" },
+      { type: "uint256" },
+      { type: "bytes32" },
+    ],
+    [
+      request.from,
+      request.to,
+      request.token,
+      request.txGas,
+      request.tokenGasPrice,
+      request.batchId,
+      request.batchNonce,
+      keccak256(request.data),
+    ],
+  );
+
+  const signature = await account.signMessage({ message });
+
+  return [request, signature] as const;
+}
+
+/**
+ * @internal
+ */
+export async function relayBiconomyTransaction(
+  options: SendBiconomyTransactionOptions,
+): Promise<WaitForReceiptOptions> {
+  const [request, signature] = await prepareBiconomyTransaction(options);
+
+  // send the transaction to the biconomy api
+  const response = await fetch(
+    "https://api.biconomy.io/api/v2/meta-tx/native",
+    {
+      method: "POST",
+      body: stringify({
+        apiId: options.gasless.apiId,
+        params: [request, signature],
+        from: request.from,
+        to: request.to,
+        gasLimit: request.txGas,
+      }),
+      headers: {
+        "x-api-key": options.gasless.apiKey,
+        "Content-Type": "application/json;charset=utf-8",
+      },
+    },
+  );
+  if (!response.ok) {
+    response.body?.cancel();
+    throw new Error(`Failed to send transaction: ${await response.text()}`);
+  }
+  const json = await response.json();
+  const transactionHash = json.txHash;
+  if (isHex(transactionHash)) {
+    return {
+      transactionHash: transactionHash,
+      chain: options.transaction.chain,
+      client: options.transaction.client,
+    };
+  }
+  throw new Error(`Failed to send transaction: ${stringify(json)}`);
+}