Home

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:

Source Code:

SDK

The main module has the following functions built-in:


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:

ParamsTypeDescription
feeTokenstringREQUIRED: The fee token address
gasLimitstringREQUIRED: The gas limit - this value is used for calculating the maximum fee token amount, it may not be the actual gas limit provided to the transaction
gasPricestringREQUIRED: The gas price - this value is used for calculating the maximum fee token amount, it may not be the actual gas price provided to the transaction
durationstringREQUIRED: The duration in seconds until the meta-txn expires
domainNamestringREQUIRED: The EIP712 domain name
useOraclePriceFeedbooleanREQUIRED: True: use an oracle price feed as a source to fetch fee token price, false: otherwise
extendCategoriesArray<number>REQUIRED: An array of numeric categories that maps to the request extension type. Pass the [0] value to omit extensions. To request an N-amount of extensions, provide an array of N-size with their corresponding categories. For example, to request x2 randomly generated numbers, input [1,1]
fromAddressstringREQUIRED: This can be an EOA address or a smart contract address to support EIP 1271 Signature Verification. If an EOA address is provided, it must match the signing address, otherwise the transaction will fail.
targetAddressstringREQUIRED: The address of the implementation contract
targetAbistringREQUIRED: The abi of the implementation contract
methodNamestringREQUIRED: The name of the method to invoke
paramsArray<any>OPTIONAL: The method parameters to be stored as an array

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.

CategoryDescription
0No extension
1VRF Generated Random Number