EssentialSigner 🤝 Your dApp

Learn how to integrate Cross-Chain Token Gating into your frontend with 0xEssential's SDK

0xEssential provides a client SDK you can use in your dApps to easily implement network-agnostic meta-transaction signing that's compatible with the cross-chain token gating flow.

The SDK extends ethers and offers the EssentialSigner class. Use an EssentialSigner to connect to your Layer 2 Implementation Contract - the SDK will route all non-payable transactions through your relayer, including the required payload to perform the cross-chain token gating.

Install & Config

0xessential/signers is available as an NPM package. Install it with npm or yarn:

yarn add @0xessential/signers

// or

npm i @0xessential/signers

The package is written natively in Typescript and provides type definitions. You can review the source code on Github.

The SDK expects you to set some ENV vars in your dApp's environment:

CHAIN_ID

The chain ID value for the chain where your implementation contract lives. 0xEssential currently supports Polygon's Mumbai testnet (80001) and Matic mainnet (137).

RELAYER_URI

The SDK will handle submitting meta-transaction requests to your relayer. To do so the SDK needs to know the URI of the relaying service. This can be a fully qualified URL or a relative path.

Usage

EssentialSigner is an extension of ether's AbstractSigner so we recommend using ethers in your dApp .

You don't need to worry about EIP712 meta-transaction payloads - the SDK allows you to interface with ethers Contract instances as you normally would, but requires you to pass an EssentialSigner to your Contract constructor.

The EssentialSigner constructor requires the address for the EOA who will perform the signing and an instance of a Web3Provider for that address with the capability to sign messages.

import { EssentialSigner } from '@0xessential/signers';
import { Contract } from '@ethersproject/contracts';

import MyContract from '../../abis/MyContract.json';
import { MyContract as TMyContract } from '../../typechain';


const Layer2ImplementationContract = new Contract(
    MyContract.address,
    MyContract.abi,
    new EssentialSigner(address, provider),
 ) as TMyContract;

When you want to submit a meta-transaction with cross-chain token-gating, you call your contract like you normally would, but must include the NFT's chain ID, contract address and token ID in the customData key:

const callGatedTrasnaction = async (
nftContract: string,
nftTokenId: BigNumberish
) => {
  const { hash } = await Layer2ImplementationContract.tokenGatedFunc("a string arg", {
    customData: {
      nftChainId: '1',
      nftContract,
      nftTokenId,
    },
  });

Assuming your relaying service is properly implemented to submit the transaction and return the transaction hash, you'll receive that hash once the transaction is submitted.