openzeppelin/starter-kit-gsn

An OpenZeppelin starter kit focused on GSN.

⚠️ This project is deprecated. We are no longer actively developing new features nor addressing issues. Read here for more info, and reach out if you are interested in taking over maintenance. We suggest looking into create-eth-app for a popular alternative to this project.

OpenZeppelin GSN Starter Kit

An OpenZeppelin Starter Kit GSN containing React, OpenZeppelin CLI, OpenZeppelin Contracts, Gas Station Network, Truffle and Infura.

OpenZeppelin GSN Starter Kit comes with everything you need to start using Gas Station Network contracts inside your applications. It also includes all the GSN Providers & Web3 connectors that you need to abstract gas for your users.

In addition to the contents included in the vanilla Starter Kit, this kit contains a step-by-step tutorial on how to enable Gas Station Network for a simple Counter Contract.

Requirements

Install Ganache, and Truffle

npm install -g [email protected] [email protected]

Installation

Ensure you are in a new and empty directory, and run the unpack command with gsn to create a starter project:

npx @openzeppelin/cli unpack gsn

Run

In a new terminal window, run your local blockchain:

ganache-cli --deterministic

In your original terminal window, at the top level of your folder, initialize the project and follow the prompts:

npx openzeppelin init

In a new terminal window, in the client directory, run the React app:

cd client
npm run start

Follow the instructions in the browser.

Test

Truffle can run tests written in Solidity or JavaScript against your smart contracts. Note the command varies slightly if you're in or outside of the truffle development console.

// inside the development console.
test

// outside the development console..
truffle test

Jest is included for testing React components. Compile your contracts before running Jest, or you may receive some file not found errors.

// ensure you are inside the client directory when running this
npm run test

Build

To build the application for production, use the build script. A production build will be in the client/build folder.

// ensure you are inside the client directory when running this
npm run build

Why this kit?

This kit leverages GSN to create dapps that are ready for mass adoption. Free your users from the initial burden of installing Metamask and obtaining Ether. Create blockchain applications that are indistinguishable from Web2.0 apps.

This documents assumes familiarity with the Gas Station Network. Check out our GSN getting started guide and GSN Kit Tutorial to learn more.

How does it use Web3 with GSN?

This kit uses Open Zeppelin network.js to create the connection to Web3. Using a couple of flags for development and production you can see how the dapp obtains a context that is aware of Gas Station Network.

// get GSN web3
const context = useWeb3Network("http://127.0.0.1:8545", {
  gsn: { dev: true }
});

How are the contracts modified to use GSN?

The Counter contract is modified to inherit from RelayRecipient. Also, the Counter contract is going to naively pay for all the transactions that are submitted. Note how the acceptRelayedCall determines this by returning 0. Also _preRelayedCall and _postRelayedCall methods must be implemented because they are defined as abstract in GSNRecipient.

pragma solidity ^0.5.0;

import "@openzeppelin/contracts-ethereum-package/contracts/GSN/GSNRecipient.sol";
import "@openzeppelin/upgrades/contracts/Initializable.sol";

contract Counter is Initializable, GSNRecipient {
  //it keeps a count to demonstrate stage changes
  uint private count;
  address private _owner;

  function initialize(uint num) public initializer {
    GSNRecipient.initialize();
    _owner = _msgSender();
    count = num;
  }

// accept all requests
  function acceptRelayedCall(
    address,
    address,
    bytes calldata,
    uint256,
    uint256,
    uint256,
    uint256,
    bytes calldata,
    uint256
    ) external view returns (uint256, bytes memory) {
    return _approveRelayedCall();
  }  ...
}

  function _preRelayedCall(bytes memory context) internal returns (bytes32) {
      // solhint-disable-previous-line no-empty-blocks
  }

  function _postRelayedCall(bytes memory context, bool, uint256 actualCharge, bytes32) internal {
      // solhint-disable-previous-line no-empty-blocks
  }

How to know if my recipient has funds?

The frontend also has some functions to help you see how much remaining balance you have left. Once it runs out, transactions will stop working because your dapp won't be able to pay the gas fee on behalf of its users.

const getDeploymentAndFunds = async () => {
  if (instance) {
    const isDeployed = await isRelayHubDeployedForRecipient(lib, _address);
    setIsDeployed(isDeployed);
    if (isDeployed) {
      const funds = await getRecipientFunds(lib, _address);
      setFunds(funds);
    }
  }
};

You can top your balance by sending funds to your contract using npx oz-gsn fund-recipient --recipient ADDRESS command or heading to the dapp tool.

How is the RelayHub deployed locally?

When you run npx oz-gsn fund-recipient, the following code gets executed:

// Ensure relayHub is deployed on the local network
if (options.relayHubAddress.toLowerCase() === data.relayHub.address.toLowerCase()) {
  await deployRelayHub(web3, options.from);
}

Note that on both mainnet and testnets, as well as local blockchain (ganache) environments, the address of the RelayHub contract is always 0xD216153c06E857cD7f72665E0aF1d7D82172F494.

FAQ

• How do I use this with the Ganache-CLI?

  It's as easy as modifying the config file! Check out our documentation on adding network configurations.

• Where is my production build?

  The production build will be in the client/build folder after running npm run build in the client folder.

• Where can I find more documentation?

  Check out the OpenZeppelin Starter Kits documentation.

starter-kit-gsn's Issues

Consider removing upgradablity tasks in tutorial.

In going through the Start-kit-gsn for workshops and with individuals, I have noticed that the upgradability portion of the tutorial introduces friction to the learning experience. As the OZ method of upgrades is an in depth subject itself, perhaps its best if we keep the GSN Starter Kit focused just on the GSN. The uncommenting process for upgradability lead to a number of a different simple mistakes that nonetheless took significant time to debug.

./node_modules/web3-eth-accounts/src/scrypt.js Critical dependency: the request of a dependency is an expression

Running the client npm start in the client directory gives the following warning:

Compiled with warnings.

./node_modules/web3-eth-accounts/src/scrypt.js
Critical dependency: the request of a dependency is an expression

Search for the keywords to learn more about each warning.
To ignore, add // eslint-disable-next-line to the line before.

Checking dependencies:

$ npm ls web3-eth-accounts
[email protected] /c/Users/andre/Documents/projects/forum/starter/client
└─┬ [email protected]
  └─┬ [email protected]
    └── [email protected]

The issue is apparently resolved in [email protected] according to: web3/web3.js#3018

Document how the RelayHub is instantiated locally

It's not obvious where and how the RelayHub gets deployed locally. I know that it's always located at 0xD216153c06E857cD7f72665E0aF1d7D82172F494, but it'd be great to have more details about it.

Error: A web3 provider is not attached to a window.

When running the GSN Starter Kit in a browser without injected Web3 (e.g. MetaMask) the following error is displayed: Error: A web3 provider is not attached to a window.

The starter kit includes no Web3 handling code that isn't used.:

  function renderNoWeb3() {
    return (
      <div className={styles.loader}>
        <h3>Web3 Provider Not Found</h3>
        <p>Please, install and run Ganache.</p>
      </div>
    );
  }

Need to update the kit with a working no Web3 pattern.

Starter Kit has no tests set in Package.json

In Starter-Kit-GSN there is no test specified in the Package.json.

Wrong address in UI

Before creating the Counter instance and funding the recipient, I see the correct address under "Web3 Provider".

After that, I see a bogus address. 0xC957... is not my MetaMask account.

ERROR : ln' is not recognized as an internal or external command

when I command 'npm install @openzeppelin/network' on powershell it returns error :

ln' is not recognized as an internal or external command

Error: Invalid number of parameters for "initialize". Got 2 expected 0!

Please correct me if I am wrong. As below shows, This error was caused by there's two initialize() functions and the test case was calling the one with 0 parameters.

And it can be fixed by renaming it e.g. rename initialize to initialise.