Hacker Guide: MetaMask Delegation Toolkit ERC-7715 actions

# **Hacker Guide: MetaMask Delegation Toolkit ERC-7715 actions** ## **Introduction** This guide provides a comprehensive overview of the experimental ERC-7715 actions in MetaMask delegation toolkit, an innovative tool that allows dApps to request and manage user permissions for specific actions, such as token transfers. This enables exciting new use cases like subscriptions and automated payments, all while enhancing the user experience. We'll explore the underlying concepts, guide you through setting up your development environment, and walk through the process of building a dApp that leverages the Gator SDK. This guide will use Viem for blockchain interactions. ## **Fundamentals: Rethinking Web3 Transactions** ERC-7715 introduces a new paradigm for how dApps interact with user wallets. Instead of requiring users to manually approve every transaction, dApps can request permission to perform certain actions on the user's behalf, within predefined limits. ### **Key Concepts** * **Session Account:** The dApp's account (either an EOA or a smart contract) that is granted permission to act on the user's behalf. * **User Wallet:** The user's MetaMask wallet, which grants permissions to the session account. * **Permissions:** Specific actions that a dApp is authorized to perform. The Gator SDK currently supports native-token-stream. * **Gator Smart Account:** A smart account created within the user's MetaMask Snap, specifically for managing permissions granted via the Gator SDK. * **Delegation:** The core mechanism that makes permission-based transactions possible. When a user grants permission, a delegation is created from their Gator Smart Account to the dApp's session account. This establishes an off-chain authorization, allowing the dApp to execute specific actions under defined conditions without requiring the user to sign each individual transaction. It's like setting up a recurring allowance with rules. * **ERC-7715 (Wallet Permission Requests):** A standard for how dApps request permissions from user wallets. https://eip.tools/eip/7715 * **ERC-7710 (Smart Contract Delegation):** A standard for how smart contracts can delegate capabilities to other accounts. https://eip.tools/eip/7710 * **MetaMask Snaps:** A system that allows developers to extend the functionality of MetaMask. Snaps are essentially plugins that can extend MetaMask's functionality, allowing it to support new blockchains, new transaction types, and, in the case of the Gator SDK, advanced permission management. The Gator SDK relies on two Snaps: * **Permission Kernel Snap:** Acts as a router to the specific permissions provider snap. In our case the Gator Permission snap. * **Gator Permissions Snap:** Creates and manages the user's Gator Smart Account. This snap handles providing the user with the Permission Picker UI and allowing them to edit permissions and grant / reject them. * **ERC-4337:** Account Abstraction standard, which enables more flexible smart accounts and transaction management, often used in conjunction with Gator SDK. https://eip.tools/eip/4337 * **Bundler:** A service that bundles multiple user operations (transactions) into a single transaction, optimizing gas usage. * **Paymaster (Optional):** A smart contract that can pay for the gas fees of transactions, allowing for gasless transactions for the user. ### **How It Works** The Gator SDK, in conjunction with MetaMask Snaps, ERC-7715, and ERC-7710, enables a permission-based workflow: 1. **Permission Request:** The dApp, acting as the session account, initiates a permission request. This is done using the wallet\_grantPermissions method, standardized in ERC-7715. The dApp specifies the type of permission (e.g., native-token-stream), the target (its own address), and any specific parameters (e.g., amount). 2. **User Authorization:** MetaMask Flask presents the permission request to the user. If the required Snaps are not already installed, MetaMask Flask will prompt the user to install them at this point. The user is then presented with a clear and understandable explanation of what the dApp is requesting. The user can then approve or reject the request. The Permission Kernel Snap plays a key role in this interaction, ensuring the user understands the permissions being requested. 3. **Gator Smart Account Creation:** If the user approves the permission, the Gator Permissions Snap takes action.. This Smart Account is where the delegated authority will originate. 4. **Funding Gator Account:** The user is responsible for funding this Gator Smart Account with sufficient funds to cover the delegated actions. For example, if the permission is for native-token-stream, the user needs to deposit the relevant native token into their Gator Smart Account. 5. **Delegation Creation:** This is a crucial step. A delegation is created, establishing the link between the user's Gator Smart Account and the dApp's session account. This delegation, governed by ERC-7710, authorizes the dApp to act on behalf of the user, but only within the boundaries of the granted permission. The delegation specifies: * The actions the dApp can perform (e.g., transfer native tokens). * Any conditions or limitations (caveats), such as: * Maximum amount per transfer * Frequency of transfers * Expiration date 6. **Permission Redemption (Delegated Action):** When the dApp needs to perform an action within the scope of the granted permission, it "redeems" the delegation. This involves the dApp constructing a transaction (or User Operation, if using ERC-4337) that adheres to the rules set out in the delegation. The dApp then submits this transaction (or User Operation, if using ERC-4337), providing proof of the valid delegation. ## **Setting Up Your Development Environment** ***Please note that the snaps for ERC-7715 actions specifically work only with sepolia. So please use sepolia if you hack for the ERC-7715 track. For Other features in the Delegation Toolkit you can use any test network mentioned [here](https://docs.gator.metamask.io/changelog/0.10.1#supported-testnet-networks)*** ### **Prerequisites** * **Node.js:** Ensure Node.js is installed on your system. * **MetaMask Flask:** Install MetaMask Flask, a developer-focused version of MetaMask. Download it from the [official MetaMask site](https://docs.metamask.io/snaps/get-started/install-flask/). **Important: Use a separate browser profile for Flask. If you use the same browser with your Regular MetaMask wallet, please disable it.** * **MetaMask Snaps:** The Snaps required for the Gator SDK (Permission Kernel Snap and Gator Permissions Snap) can be installed manually, or MetaMask Flask will prompt the user to install them when a dApp requests permissions for the first time. * **ERC-4337 Bundler:** This is required if the session account is an ERC-4337 wallet. In order to send user operations from ERC-4337 wallet you'll need access to a bundler. [Pimlico](https://docs.pimlico.io/infra/bundler/usage) is a good option. See their documentation. * **Paymaster (Optional):** If you want to sponsor gas fees, you'll need a paymaster. Pimlico also provides paymaster services. ### **Installation Steps** 1. **Install Node.js:** Download and install Node.js from the official website. 2. **Install MetaMask Flask:** * Open a new browser profile. * Go to the MetaMask Flask download page on the MetaMask website. * Download and install the MetaMask Flask extension. 3. **Set up a Bundler:** * If using Pimlico, create an account on their platform. * Obtain your bundler API key from Pimlico. * Familiarize yourself with how to send user operations to the Pimlico bundler. 4. **Set up a Paymaster (Optional):** * If using Pimlico, you can also use their paymaster service. Configure your dApp to use the paymaster. ## **Building a dApp with Gator ERC7715 Actions** The easiest way to get started with Gator ERC7715 actions is with the create-gator-app CLI, which has a template called `Experimental: Basic Gator app to try out ERC7715 Permissions`. This template comes with all the required basic libraries and code snippets installed. You can run the CLI with ``` npx create-gator-app@latest ``` If you prefer to use the SDK in a repo from scratch, you can follow these instructions to install the `@metamask/delegation-toolkit` SDK. ERC-7715 related functions are exported from `@metamask/delegation-toolkit/experimental` package Here are the main functions to handle ERC-7715 actions:cx Please refer these sections of the documentation for most important code snippets * Granting a permission: [https://docs.gator.metamask.io/experimental/erc-7715](https://docs.gator.metamask.io/experimental/erc-7715) * Redeeming a permission: [https://docs.gator.metamask.io/experimental/erc-7710](https://docs.gator.metamask.io/experimental/erc-7710) * Creating a gator account, if you want to use a gator account as the session account: [https://docs.gator.metamask.io/how-to/create-delegator-account](https://docs.gator.metamask.io/how-to/create-delegator-account) ## **Resources** * Official Documentation (Checkout Experimental packages for ERC7715 actions) : [https://docs.gator.metamask.io/](https://docs.gator.metamask.io/) * Hackathon page in Hackquest: view [here](https://www.hackquest.io/hackathons/MetaMask-Delegation-Toolkit-DTK-Dev-Cook-Off) * `create-gator-app` CLI : view [here](https://hackmd.io/@x2AtdNlxSjuUiT4xerbPSg/Byy9hijCJe) * Starter repos: In case you encounter an issue with the CLI, try cloning these starter repos. - ERC-7715 NextJS starter: https://github.com/MetaMask/templated-gator-7715 - NextJS Delegation Toolkit starter: https://github.com/MetaMask/gator-nextjs-starter * Get help - Consensys discord channel, look for `mm-dtk` channel: Join [here](https://discord.gg/consensys-697535391594446898) - MetaMask Developer Chat Telegram group. Checkout `MetaMask Delegation Toolkit` group: Join [here](https://t.me/+I2dliwXiqqYyYjMx)