@automata-network/conveyor-sdk

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:

Params	Type	Description
feeToken	string	REQUIRED: The fee token address
gasLimit	string	REQUIRED: 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
gasPrice	string	REQUIRED: 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
duration	string	REQUIRED: The duration in seconds until the meta-txn expires
domainName	string	REQUIRED: The EIP712 domain name
useOraclePriceFeed	boolean	REQUIRED: True: use an oracle price feed as a source to fetch fee token price, false: otherwise
extendCategories	Array	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]
fromAddress	string	REQUIRED: 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.
targetAddress	string	REQUIRED: The address of the implementation contract
targetAbi	string	REQUIRED: The abi of the implementation contract
methodName	string	REQUIRED: The name of the method to invoke
params	Array	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.

Category	Description
0	No extension
1	VRF Generated Random Number