DOCSEARCHbyAlgolia
Submit Docs

Gas Station Network (GSN)

repository·master·Indexed 20 days ago

https://github.com/opengsn/gsn

A distributed network of transaction relayers that allows decentralized applications to abstract away gas fees for gasless user experiences. The project includes the @opengsn/cli for deployment, @opengsn/contracts for Solidity source code, @opengsn/provider for client-side Web3 integration, and @opengsn/dev for testing via GsnTestEnvironment. It features various Paymaster implementations (AcceptEverything, Whitelist, Token, and ProxyDeploying) and a Relay Server deployable via the opengsn/jsrelay Docker image.

Tokens
34.8K
Snippets
95
Records
128
Agent score
70%

What's inside opengsn/gsn

  1. Overview of GSN smart contracts

    master
    The @opengsn/contracts module provides the core Solidity smart contracts for the Ethereum Gas Station Network (GSN). GSN is designed to abstract away gas fees to minimize onboarding and user experience friction for decentralized applications (dapps). This package includes the Solidity source code and corresponding TypeScript type declarations for integration into TypeScript-based development environments.

  2. Identify the correct GSN package for your needs

    master

    Depending on your integration goal, you may need a different GSN package instead of the Relay Server source:

    • Client-side dapps: Use @opengsn/provider to integrate a Web3 provider into your JavaScript frontend that uses GSN to relay transactions.
    • Smart Contract development: Use @opengsn/contracts to access GSN smart contracts written in Solidity and their corresponding TypeScript type declarations.
    • Integration and Testing: Use @opengsn/cli for command-line tools to help integrate GSN, test integrations locally, or deploy relay servers on public Ethereum networks.

  3. Use the GSN Web3 Provider for client-facing dapps

    master
    The @opengsn/provider module provides a Web3 provider designed for client-side JavaScript dapps. It abstracts away gas management by using the Gas Station Network (GSN) to relay transactions, which helps minimize onboarding friction and improve user experience by removing the need for users to hold native gas tokens for every interaction.

  4. Use TokenPaymaster for token-based gas payments

    master

    The TokenPaymaster allows users to pay for gas using a specific ERC20 token instead of ETH.

    How it works:

    1. The calling account must provide an approval for the paymaster to pull tokens from its account.
    2. For accounts without ETH, this approval can be handled via methods like DAI's permit.
    3. The paymaster pre-charges the user with the equivalent value of tokens before the call.
    4. After the call, the paymaster refunds any excess tokens to the user.

  5. Use WhitelistPaymaster for controlled access

    master
    The WhitelistPaymaster protects against anonymous attacks by only accepting requests from a specific list of known, authorized addresses. While more secure than AcceptEverythingPaymaster, it requires an administrative step to whitelist all valid client addresses.

  6. How the GSN architecture works

    master

    The Gas Station Network (GSN) consists of three main components that enable gasless transactions:

    1. Relay Server: A Node.js server that receives Relay Requests and broadcasts them to the blockchain. It pays for gas out-of-pocket and is reimbursed by the GSN Smart Contracts.
    2. Relay Provider: A TypeScript Node module that wraps existing Ethereum providers (Web3.js, Ethers.js, MetaMask, etc.) to route transactions through the GSN.
    3. GSN Smart Contracts: Core singleton contracts on each network, including:
      • RelayHub: The central contract connecting users, relay servers, and paymasters.
      • Forwarder: Verifies the sender's signature and nonce.

    To participate, a Dapp requires two additional contract roles:

    • Paymaster: A contract that holds Ether to subsidize user transactions.
    • Recipient: The target contract receiving the transaction. It must inherit from ERC2771Recipient to support GSN calls.

  7. Understand GSN Paymasters

    master
    A GSN paymaster is a smart contract designed to pay for relayed requests. The primary purpose of using a paymaster in the Gas Station Network (GSN) is to allow calling accounts to execute transactions even if they lack ETH, by shifting the gas cost responsibility to the paymaster contract.

  8. Use ProxyDeployingPaymaster for proxy account management

    master

    The ProxyDeployingPaymaster is a specialized version of the TokenPaymaster. In addition to handling token-based payments, it can also deploy a proxy account for the user.

    Because the paymaster performs the deployment, it can also trigger the proxy to 'approve' the token. This allows the paymaster to charge the account for both the proxy creation and all subsequent requests using tokens.

  9. Use AcceptEverythingPaymaster for testing

    master

    The AcceptEverythingPaymaster is a naive implementation that accepts any request from any client.

    Warning: Do not deploy this on a mainnet or production network. Because it lacks access controls, any client can make unlimited requests, which will quickly drain the paymaster's balance.

  10. Set up a local registry for testing with Verdaccio

    master

    To test local builds within the GSN repository, you can run a local Verdaccio registry. This allows you to publish local packages and test them as if they were on npm.

    1. Start the registry: In a separate background terminal, run:
      yarn verdaccio-start
    2. Publish local builds: Use the following command to publish your local build into the repository:
      yarn verdaccio-publish
      Note: This requires a clean git state and a local commit, but it does not push to any remote repository.
    3. Initialize a test app: Instead of using standard yarn, use the specialized GSN yarn wrapper to ensure @opengsn packages are fetched from the local Verdaccio registry (falling back to npmjs.com if necessary):
      yarn gsn/verdaccio/yarn
      (This command executes yarn --use-yarnrc=gsn/verdaccio/yarnrc)
    yarn verdaccio-start
yarn verdaccio-publish
yarn gsn/verdaccio/yarn

  11. Run a Relay Server

    master
    You can join the GSN by running your own Relay Server. A docker-compose script is provided in the repository to simplify this process. Running your own relay is recommended for Dapp developers to save costs by avoiding third-party transaction fees.