React

Gasless Transactions from a React App

Our React package is designed to fit with your existing tools and workflow, making it easy to adopt, evaluate, and rage-quit if it's not the right fit for your application. You shouldn't have to entirely rework how you build Ethereum applications to adopt Gasless Transactions, and you shouldn't have to get locked in to using our SDK because of high switching costs.

Our React SDK, @xessential/react is based on wagmi. It provides hooks with the same API as hooks from wagmi - usePrepareContractWrite and useContractWrite can be imported from @xessential/react, replacing wagmi imports, and the only additional change you need to make is to specify the NFT a user wishes to use.

If you are not using wagmi, first review the wagmi React Getting Started guide. Once you've wrapped your app with a <WagmiConfig> you're ready to install and configure @xessential/react for NFT Global Entry.

Installation

You can install the SDK from NPM with

yarn add @xessential/react

or

npm install @xessential/react

EssentialProvider

Import EssentialProvider and add it to your app as a child of <WagmiConfig>.

import { EssentialProvider } from '@xessential/react';

function App() {
  return (
    <WagmiConfig client={client}> // follow wagmi docs for client setup
      <EssentialProvider
        config={{
          forwarderAddress: "0x000000000066b3aED7Ae8263588dA67fF381FfCa", //default
          rpcUrl: YOUR_L2_RPC_URL,
          relayerUri: 
        }}
      >
        <YourRoutes />
      </EssentialProvider>  
    </WagmiConfig>
  )
}

forwarderAddress

Specify the address of the EssentialForwarder you're using. Will default to the canonical deployment at 0x000000000066b3aED7Ae8263588dA67fF381FfCa.

relayerUri

See our Relayer guide for more info on setting up your relayer service. Meta-transaction requests will be submitted here. We recommend a proxy API to an Open Zeppelin Defender Autotask.

rpcUrl

Provide a network-specific RPC URL for the chain where you will submit Global Entry transactions. If left blank, the SDK will use a rate-limited fallback provider.

Usage

Now you can use Global Entry enabled hooks! Every component inside the EssentialProvider is now set up to use the wagmi-based hooks that depend on NFT Global Entry.

By default, these hooks will use the connected wallet from wagmi's useAccount hook for submitting transactions.

usePrepareContractWrite => useContractWrite

If you're familiar with wagmi you'll be comfortable with this approach already. Preparing the contract write prior to the user clicking a button to submit a transaction allows us to prepare the transaction for an instant wallet popup.

In the Global Entry context, when you prepare a contract write for a standard transaction, usePrepareContractWrite fetches the ownership proof in preparation of submitting the transaction.

To specify the NFT to use, include the chain ID, contract address and token ID for the NFT in overrides.customData:

import { usePrepareContractWrite, useContractWrite } from '@xessential/react'

const L2_CONTRACT_ADDRESS = '0x1...';
const L2_CONTRACT_ABI = {/*...*/} as const;
const NFT_CONTRACT_ADDRESS = '0x2...';

function App() {
  const { config, error } = usePrepareContractWrite({
    address: L2_CONTRACT_ADDRESS,
    abi: L2_CONTRACT_ABI,
    functionName: 'tokenGatedFunction',
    overrides: {
      customData: {
        nftChainId: 1,
        nftContract: NFT_CONTRACT_ADDRESS,
        nftTokenId: 69,
      }
    }
  });
  const { write } = useContractWrite(config)
 
  return (
    <>
      <button disabled={!write} onClick={() => write?.()}>
        Submit Global Entry TX
      </button>
      {error && (
        <div>An error occurred preparing the transaction: {error.message}</div>
      )}
    </>
  )
}

So far we are assuming that the connected address directly owns the NFT being used in this transaction. If the connected address does in fact own that NFT, 0xEssential's NFT Ownership Oracle will generate and attach the ownership proof to the config return value, and include it when the write function is executed, allowing the transaction to be submitted and validated.

The APIs and return value for these hooks are exactly the same as the wagmi hooks. However you prefer handling callbacks and validation state will continue to work.