Awesome

Introduction

The Conveyor SDK is a JavaScript library for developers to seamlessly interact with smart contracts that benefit from MEV protection with Conveyor.

Long story short, users submit meta-transactions to their contracts by following the three-step process below:

1. Instantiate the module and set your Web3 provider
2. Approve the Forwarder contract to collect fee payment with your choice of ERC20 tokens*.
3. Submit a request and provide the necessary parameters.

*ERC20 token must be enlisted on CoinGecko as a measure to determine market value, otherwise the transaction may be rejected for unsupported fee token.

Specification

Smart Contract

Implementation smart contracts must inherit the ConveyorBase contract. The ConveyorBase contract includes the following administrative methods:

• Toggle Conveyor protection using the enableConveyorProtection and disableConyerProtection methods.
• Configure the trusted forwarder address with setForwarder.
• The onlyConveyor modifier. Functions with the modifier can only be invoked by none other than the Forwarder contract.
• To retrieve the sender's address on the implementation contract, you must use the msgSender() instead of the default msg.sender.

Source Code:

• ConveyorBase: https://github.com/automata-network/generic-conveyor/blob/main/contracts/ConveyorBase.sol
• Example Contract: https://github.com/automata-network/generic-conveyor/blob/main/contracts/test/Greeter.sol

SDK

The main module has the following functions built-in:

• erc20ApproveForwarder- Sets an allowance for the Forwarder contract to transfer ERC20 tokens for fee payment.
• submitMetaTransaction - Constructs the request body to the Geode relayer to interact with contracts that are protected by Conveyor. (Note: The submitConveyorTransaction() method has been deprecated, it will be removed in future releases)
• submitTransaction - Submits a regular transaction directly to the target address. This can be used to execute methods that do not have the onlyConveyor modifier or to contracts that have disabled Conveyor protection.
• fetchConveyorStatus - detects whether Conveyor protection is enabled for the given target contract.
• toggleConveyorProtection - enables/disables Conveyor protection on the given target contract.

Configurable Variables

The default RELAYER_ENDPOINT_URL and FORWARDER_ADDRESS are included in the SDK. This is because most projects are likely using the same relayer and Forwarder contract. If your projects were assigned to a dedicated relayer and/or forwarder, you may simply overwrite those variables, by passing the following object as a parameter to initialize the Conveyor module.

// This is optional and overwrites the canon relayer and forwarder
const options = {
  forwarder: '0x84194C00E190dE7A10180853f6a28502Ad1A1029',
  relayerConfig: 'https://fake-relayer.com',
  env: ENVIRONMENT.TEST,
};

const conveyor = new Conveyor(web3, options);

Quick Guide

As mentioned previously, submitting a transaction using Conveyor only requires three steps.

Prerequisite

Install the SDK by running:

yarn add @automata-network/conveyor-sdk

Step 1: Instantiate the module and set your Web3 provider

import { Conveyor } from '@automata-network/conveyor-sdk';

const web3 = window.ethereum; // Metamask

const conveyor = new Conveyor(web3); // assigns default relayer and forwarder depending on chain id and the environment

Step 2: Approve the Forwarder contract for collecting fees

:warning: This step must be performed before moving on to the next step. Otherwise, your transaction may fail due to zero allowance

await erc20ApproveForwarder(
  '100000000', // 100 USDC
  '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' // USDC address on ETH
);

In the above example, the user is allocating 100 USDC of allowance to the Forwarder contract.

Step 3: Submit the transaction

The submitMetaTransaction() function requires the following parameters:

The submitTransaction() method can be invoked to execute functions that do not have the onlyConveyor modifier.

Available extensions

This section describes the category index that are passed into the extendCategories parameter to get external data that can be useful for your target contracts.