Web3 Layer

Web3 is the interface dApps use to interface with the Ethereum blockchain. Almost all of the widgets in the OpenRelay toolkit make use of Web3, so we needed a way to unify Web3 interactions across our widgets. Additionally, there are many scenarios where a user may need to take steps to enable Web3 in their browser. For example:

  • The user needs to install a Web3 plugin such as Metamask
  • The user’s Web3 plugin is locked
  • The user’s Web3 plugin is connected to a network not supported by this dApp

In these cases, your application may need to provide the user with instructions on how to configure Web3 to work with your application. The OpenRelay widget toolkit’s Web3 layer makes it easy to catch these conditions and show your users what they need to know without having to write any custom JavaScript to detect these conditions.

<or-web3>

Every widget from the OpenRelay Widget Toolkit should have an <or-web3> tag (or a tag providing equivalent functionality) somewhere in its ancestry. This means you will probably want to build much of your application underneath an <or-web3> tag.

A simple example of a full HTML page might look like this:


<html>
  <head>
    <title>Your dApp</title>
    <script src="https://widgets.openrelay.xyz/v0.1.1/assets/js/widgets-bundle.js"
            integrity="sha256-mJLaKF5oAV22lf22JinmrlapIN2L1EOxqBI/chTggN8=">
    </script>
  </head>
  <body>
    <h1>Your dApp's Header</h1>
      <or-web3>
        Your dApp's <strong>HTML</strong> goes <a href="#">here</a>.

        <!-- End of main dapp code -->

        <div slot="noweb3">
          Invite your users to get <a href="https://metamask.io/">Metamask</a>
        </div>

        <div slot="locked">
          Instruct your users to <strong>Unlock Web3<</strong>.
        </div>
        <div slot="netunsupported">
          Tell your users to switch to Mainnet or Kovan.
        </div>
        <!--
          Here we can list the network IDs of supported networks.

          If no elements with slot="net" are listed, all networks are implicitly
          supported.
        -->
        <div slot="net">1</div>
        <div slot="net">42</div>
      </or-web3>
    <footer>&copy; Your dApp 2018</footer>
  </body>
</html>

In this very simple example, your dApp’s header and footer will always be shown. If the user doesn’t have a Web3 client, they will see instructions to install Metamask. If the user has a Web3 client, but it’s locked, it will tell the users to unlock their Web3 client. If the user is connected to Ropsten or another unsupported test network, they will be instructed to switch to Mainnet or Kovan.

You are in complete control over what content is displayed in each situation and how it gets presented to your users. If you elect not to provide the noweb3, locked, and netunsupported slots, the <or-web3> tag provides default instructions for your users.

For more detail on how to use the <or-web3> tag, check out the widget documentation.