BatchTrade

The BatchTrade contract is the heart of 31Third's protocol and enables executing multiple token interactions (trades, wrapping, staking, ...) within one transaction. This page describes how the contract is setup and how batch trades can be executed by fetching rebalancings from the 31Third API and executing them via the batchTrade()-function on-chain.

Configuration

With the deployment of our protocol a few configurations have been made and will be explained here for transperancy.

ExchangeAdapterRegistry

This is a registry contract storing all supported integrations handling how to call external protocols like the 0x ExchangeProxy or contracts like Wrapped Ether. It is set on BatchTrade deployment and is immutable.

Fees

31Third charges fees on batch trades. On deployment a fee recipient wallet, active fees in basis points and max fees in basis points are configured. More on how the owner of the contract can adapt these values can be found under Owner Privilege.

Details on fees can be found on the FAQ page.

Trade Signer

Trades returned by the 31Third API include a signature which will be verified on chain to prevent sending malicious calldata to external contracts. The public key of the signer pair is set on deployment but can also be adapted by the owner for security purposes.

batchTrade(...)

This section explains how a batch trade can be executed. For the usage you have to request rebalancings from our API. If you're not familiar with the usage yet check out 31Third API.

A batch trade receives an array of Trade structs and a BatchTradeConfig struct. All passed trades are executed based on the data passed within the Trade struct array. The structs will be explained below.

The following flow diagram shows the execution flow of a batch trade. For each entry in the trades array the following flow is executed:

• Get concrete adapter for trade

• Get address of external contract, calldata and value for execution of the trade

• Transfer sell token from the sender wallet to the BatchTrade contract (has to be approved)

  • (Check if we got expected sell amount)

• Execute trade on external contract

  • (Check if we got at least min expected receive amount)

• Deduct fees and store in BatchTrade contract

• Return received token to sender wallet.

Batch trade flow

In case of error: If the execution of an external trade fails the smart contract recognizes this either by getting an error or if the minToReceive amount is not reached. If a trade failed and batchTradeConfig.revertOnError is false already executed trades will stay executed and the transaction will stop here. If the minToReceive amount is not reached or batchTradeConfig.revertOnError is true, the whole execution is reverted.

Trade struct

struct Trade {
  string exchangeName;            // Name of the exchange the trade should be executed
  address from;                   // Address of the token to sell
  uint256 fromAmount;             // Amount of the token to sell
  address to;                     // Address of the token that will be received
  uint256 minToReceiveBeforeFees; // Minimal amount to receive
  bytes data;                     // Arbitrary call data which is sent to the exchange
  bytes signature;                // Signature to verify received trade data
}

BatchTradeConfig struct

struct BatchTradeConfig {
  bool checkFeelessWallets; // Determines if a check for feeless trading should be performed
  bool revertOnError;       // If true, batch trade reverts on error, otherwise execution just stops
}

Usage example with ethers.js

The 31Third API returns a DTO containing the following properties:

export interface RebalancingResponseDto extends BaseEntityModel {
  ...
  txHandler: Address;    // address of deployed BatchTrade
  txData: string;        // calldata containing encoded Trades and BatchTradeConfig
  txValue: BigNumberDto; // value native currency sent for trading
  ...
}

which can be passed into ethers signer.sendTransaction as follows:

signer.sendTransaction({
  to: rebalancing.txHandler,
  data: rebalancing.txData,
  value: rebalancing.txValue,
});