docs.opengsn.orgEthereum Gas Station Network (GSN) | v3.0.0-beta.3

pre-release v3.0.0-beta.3 pre-release OpenGSN.org (opens new window) Latest Stable (2.2.5) (opens new window) Forum (opens new window) Discord (opens new window) Status (opens new window) GitHub (opens new window) OpenGSN.org (opens new window) Latest Stable (2.2.5) (opens new window) Forum (opens new window) Discord (opens new window) Status (opens new window) GitHub (opens new window) Ethereum Gas Station Network (GSN) The problem Architecture Next Steps Contracts Writing GSN-capable contracts Deploying custom GSN instance JavaScript Client Getting Started Advanced configuration Command-Line tools Preparing the environment Simple Integration Walkthrough Relay Server Tutorial: Running a Relay Server for Fun and Profit Paymasters Using pre-deployed GSN Paymasters Code Reference Supported Networks Ethereum Network Görli Network Ethereum Mainnet Polygon Optimism Arbitrum Avalanche BSC Gnosis Chain FAQ The Big Picture Troubleshooting What’s new for GSNv3 Migrating from GSNv2 to GSNv3 JSDoc Client configuration Server configuration Security Audits # Ethereum Gas Station Network (GSN) Ethereum Gas Station Network (GSN) abstracts the process of paying for gas away from end users which minimizes UX friction for dapps. With GSN, gasless clients can interact with Ethereum smart contracts without users needing ETH for transaction fees. The GSN is a decentralized system that improves dapp usability without sacrificing security. Example use cases for GSN: Privacy : Enabling ETH-less withdrawal of tokens sent to stealth addresses Pay for gas in supported ERC-20 tokens : Allow users to pay for gas in ERC-20 tokens that support permit function Pay for gas off-chain : Allow users to pay for gas indirectly via a L2 rollup or a credit card Onboarding : Allow dapps to subsidize the onboarding process for new users # The problem Without GSN, anyone who sends an Ethereum transaction needs to have ETH to pay for gas fees. This forces new users to pass KYC and purchase ETH before they can start using any dapp. This can be a major hurdle for users without prior crypto experience that are unfamiliar with the concept of needing to keep ETH in their wallet for gas. This is also a UX pain for existing users that need to continually replenish their ETH balance to pay for gas fees even if they have enough ERC-20 tokens in their wallet to pay for the transactions they need. # Architecture Components : Client : signs & sends meta transaction to relay server Relay servers : submits a transaction and pays Ethereum protocol gas fees for doing so Paymaster : agrees to refund relay server for gas fees Forwarder : verifies sender signature and nonce Recipient contract : sees the original sender and executes the original transaction RelayHub : coordinates the process in a trustless way # Client: signs & sends meta transaction to relay server A meta-transaction is a fancy name for a simple idea: a relay server can send a user’s transaction and pay for the gas cost itself. Instead of signing an Ethereum transaction, which would require ETH for gas, a user signs a message containing information about a transaction they would like to execute and sends it to a relay server. # Relay servers: submits a transaction and pays Ethereum protocol gas fees for doing so Upon receiving the request to relay a transaction from the client, the Relay server will validate this transaction to make sure it pays back the amount of ETH that covers the expenses of submitting it and some extra fee to allow the relayer to turn a profit. If everything is fine, the relayer signs a native Ethereum transaction, submits it to the mempool and returns a signed transaction to the client for validation. In case anything goes wrong, the client can just pick a different relay server and try to send a transaction via a new one. This creates a "one for all and all for one" effect where taking down the frontend of any dapp is as hard as taking down the entire network. The more dapps participate the more robust the availability guarantee. # Paymaster: agrees to refund relay server for gas fees In the GSN all gas refund logic is implemented inside the Paymaster contracts. A paymaster maintains an ETH balance in the RelayHub and can implement any business logic to decide whether to accept or reject a meta transaction. For example, accepting only transactions by whitelisted users, or to the contracts methods required for onboarding users that also passed a captcha, or only transactions that include a repayment in tokens to the Paymaster, etc. To learn more about the Paymaster, see Paying for your user’s meta-transaction # Forwarder: verifies sender signature and nonce Meta transaction aware recipient contracts only rely on a small trusted forwarder contract for their security. This contract verifies the signature and nonce of the original sender. To learn more about the trusted forwarder, see Trusted Forwarder: Minimum Viable Trust # Recipient contract: sees the original sender and executes the original transaction Any public method of the recipient contract can be executed through GSN. To support meta transactions recipient contracts inherit from a simple base class (opens new window) and replace msg.sender with _msgSender() . It returns the original sender that signed the meta transaction request. It is still possible to make a native transaction call to this contract. The _msgSender() method will simply return msg.sender if the contract was called directly. # RelayHub: coordinates the process in a trustless way RelayHub connects users running clients, relay servers and paymasters so that participants don’t need to know about or trust each other. Dapp developers don’t need to understand or trust the inner workings of RelayHub in order to integrate with the GSN. Recipient contracts are not exposed to potential security issues in RelayHub. Under the hood the RelayHub helps clients discover the best third-party relay server, prevents third-party relay servers from censoring transactions, and ensures Paymasters pay back relay servers for gas fees plus transaction fees. # Next Steps To learn more about the GSN, head over to the following resources: To learn how to integrate GSN with your contracts , see Writing GSN-capable contracts . To learn how to integrate GSN with your client , see Javascript client . Edit this page (opens new window) Last Updated: 4/11/2023, 6:06:23 PM Writing GSN-capable...