Merge pull request #1339 from onflow/integration-gelato

Add Integration guide: gelato smart wallet

Author: btspoony

docs/tutorials/integrations/gelato-sw.mdx

@@ -0,0 +1,252 @@
+---
+sidebar_position: 1
+title: Gelato Smart Wallet
+description: Learn how to use Gelato Smart Wallet to enable gasless transactions on Flow EVM.
+keywords:
+  - tutorials
+  - guides
+  - flow
+  - evm
+  - smart contracts
+  - blockchain
+  - gas efficiency
+  - gas free
+  - gasless
+  - EIP-7702
+  - gelato
+  - smart wallet
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Gelato Smart Wallet Integration Guide
+
+You can use Gelato Smart Wallet to enable gasless transactions on Flow EVM. It supports features like: EIP-7702 or ERC-4337 depending on the wallet you use.
+
+## Prerequisites of using Gelato Smart Wallet
+
+You need to setup all the followings in the Gelato App to create a Gelato Sponsor API Key.
+
+### Step 1. Create Your Gelato Account
+
+Sign up on the [Gelato App] to establish an account. This account is the foundation for setting up relay tasks and managing gas sponsorships.
+
+### Step 2. Create a Relay App
+
+Within your Gelato account, create a new Relay App with the Flow EVM network.  
+For Testnet, you can first allow `Any contract` to call your relay app.
+
+![Create a Relay App](./images/gelato-1.png)
+
+:::note
+
+You can add more smart contract information and its associated chain information later in this App.  
+When set to a specific contract instead of `Any contract`, the API keys will only allow gasless transactions for calls to the designated methods within the ABI of the contract.
+
+:::
+
+### Step 3. Create/Obtain a Sponsor API Key
+
+After creating the relay app, navigate to its dashboard to locate your Sponsor API Key.
+
+![Create a Sponsor API Key](./images/gelato-2.png)
+
+This key links your Gelato setup with 1Balance for gas sponsorship.
+
+### Step 4. Deposit Funds into 1Balance
+
+To use Gelato sponsoring transactions, you need to deposit funds into 1Balance according to your target environment:
+
+- Mainnets: Deposit USDC.
+- Testnets: Deposit Sepolia ETH.
+
+Here we use Sepolia ETH as the gas fee for Testnet‘s gasless transactions.
+
+![Deposit Funds into 1Balance](./images/gelato-3.png)
+
+Here are some third party Sepolia ETH faucets you can use:
+
+- [Google Cloud Sepolia Faucet]
+- [Alchemy Sepolia Faucet]
+- [Chainlink Sepolia Faucet]
+- [Metamask Sepolia Faucet]
+
+## Send Gasless Transactions for your users
+
+After you have created a Sponsor API Key and deposited funds into 1Balance, you can use gasless transactions features for your users.  
+With the Gelato Smart Wallet SDK, developers can easily set up sponsored transactions for their applications in just a few simple steps, enabling seamless onboarding and interaction without requiring users to hold native tokens.
+
+:::note
+
+You can find the examples in the [Gelato Smart Wallet SDK] repository.
+
+:::
+
+### Step 1. Install all relevant dependencies
+
+<Tabs>
+  <TabItem value="pnpm" label="pnpm" default>
+    ```bash
+    pnpm add @gelatodigital/smartwallet viem
+    ```
+  </TabItem>
+  <TabItem value="bun" label="bun">
+    ```bash
+    bun add @gelatodigital/smartwallet viem
+    ```
+  </TabItem>
+  <TabItem value="yarn" label="yarn">
+    ```bash
+    yarn add @gelatodigital/smartwallet viem
+    ```
+  </TabItem>
+  <TabItem value="npm" label="npm">
+    ```bash
+    npm install @gelatodigital/smartwallet viem
+    ```
+  </TabItem>
+</Tabs>
+
+
+### Step 2. Setup Smart Wallet Account
+
+Import required dependencies:
+
+```ts
+import { createGelatoSmartWalletClient, sponsored } from "@gelatonetwork/smartwallet";
+import { gelato } from "@gelatonetwork/smartwallet/accounts";
+import { createWalletClient, createPublicClient, http, type Hex } from "viem";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import { flowTestnet } from "viem/chains";
+
+// Create a public client for the Flow Testnet
+const publicClient = createPublicClient({
+  chain: flowTestnet,
+  transport: http(),
+});
+```
+
+You can set up a Smart Account as per your needs.  
+Once you create the `gelato` account, the Gelato Smart Account address will be the same as your EOA, enabling EIP-7702 features.
+
+```ts
+// Prepare a normal EOA account
+const privateKey = (process.env.PRIVATE_KEY ?? generatePrivateKey()) as Hex;
+const owner = privateKeyToAccount(privateKey);
+
+// Wrap the EOA account into a Gelato Smart account
+const account = await gelato({
+  owner,
+  client: publicClient,
+});
+```
+
+Then you need to create a standard viem wallet client with the Gelato Smart Account.
+
+```ts
+const client = createWalletClient({
+  account,
+  chain: flowTestnet,
+  transport: http()
+});
+```
+
+Once you have a standard viem wallet client, you can wrap it into a Gelato Smart Wallet client with the sponsor API key.
+
+```ts
+const sponsorApiKey = process.env.SPONSOR_API_KEY;
+if (!sponsorApiKey) {
+  throw new Error("SPONSOR_API_KEY is not set");
+}
+
+const swc = await createGelatoSmartWalletClient(client, {
+  apiKey: sponsorApiKey
+});
+```
+
+### Step 3. Estimate or Send a Gasless Transaction
+
+Now you can estimate or send a gasless transaction with the Gelato Smart Wallet client.
+
+To estimate the fee and gas for a gasless transaction, you can use the `estimate` method.
+
+```ts
+const response = await swc.estimate({
+  payment: sponsored(sponsorApiKey),
+  calls: [
+    {
+      to: "0xa8851f5f279eD47a292f09CA2b6D40736a51788E",
+      data: "0xd09de08a",
+      value: 0n
+    }
+  ]
+});
+
+console.log(`Estimated fee: ${formatEther(BigInt(response.fee.amount))} FLOW`);
+console.log(`Estimated gas: ${JSON.stringify(response.gas)} GAS`);
+```
+
+To send a gasless transaction, you can use the `execute` method.
+
+```ts
+const results = await smartWalletClient.execute({
+    payment : sponsored(sponsorApiKey),
+    calls: [
+      {
+        to: "0xa8851f5f279eD47a292f09CA2b6D40736a51788E",
+        data: "0xd09de08a",
+        value: 0n
+      }
+    ]
+});
+
+console.log("userOp hash:", results?.id);
+const txHash = await results?.wait();
+console.log("transaction hash",txHash);
+```
+
+Or you can use `prepare` + `send` to send a gasless transaction.
+
+```ts
+const preparedCalls = await swc.prepare({
+  payment: sponsored(sponsorApiKey),
+  calls: [
+    {
+      to: "0xa8851f5f279eD47a292f09CA2b6D40736a51788E",
+      data: "0xd09de08a",
+      value: 0n
+    }
+  ]
+});
+
+// Other actions can be performed here
+
+const results = await swc.send({
+  preparedCalls
+});
+
+// You can listen for events from the Gelato Smart Wallet client
+results.on("submitted", (status: GelatoTaskStatus) => {
+  console.log(`Transaction submitted: ${status.transactionHash}`);
+});
+results.on("success", async (status: GelatoTaskStatus) => {
+  console.log(`Transaction successful: ${status.transactionHash}`);
+});
+results.on("error", (error: Error) => {
+  console.error(`Transaction failed: ${error.message}`);
+});
+```
+
+---
+
+## Conclusion
+
+So far, you’ve learned how to send sponsored EIP-7702 transactions using a Gelato Smart Wallet on Flow EVM.
+
+[Gelato App]: https://app.gelato.network/
+[Google Cloud Sepolia Faucet]: https://cloud.google.com/application/web3/faucet/ethereum/sepolia
+[Alchemy Sepolia Faucet]: https://www.alchemy.com/faucets/ethereum-sepolia
+[Chainlink Sepolia Faucet]: https://faucets.chain.link/sepolia
+[Metamask Sepolia Faucet]: https://docs.metamask.io/developer-tools/faucet/
+[Gelato Smart Wallet SDK]: https://github.com/gelatodigital/smartwallet/tree/master/examples