Supporting Off-Chain Token Trading

June 6, 2018 by Todd Proebsting

This post will implement a token trading “clearinghouse” that will execute multiple signed trade offers simultaneously.

A clearinghouse accepts trade offers from multiple parties and works to execute transactions among those parties. A clearinghouse may also act as a market maker and directly trade with those parties. In this post, the trades will be exchanges of ERC20 tokens for other ERC20 tokens.

For example, the clearinghouse could execute a pair of perfectly matched trades like the following:

X wants to trade 1 P for 1 Q (where P and Q are different tokens)

Y wants to trade 1 Q for 1 P

A more interesting example would be the following:

X wants to trade 3 P’s for 3 Q’s

Y wants to trade 2 Q’s for 2 P’s

Z wants to trade 1 Q for 1 P

In that case, a clearinghouse could orchestrate a simultaneous three-way trade.

While the supported trades will only involve two tokens each, that doesn’t mean that an orchestrated trade could not be for many different tokens. For instance, the following three trades could be supported:

X wants to trade 1 R for 1 S

Y wants to trade 1 S for 1 T

Z wants to trade 1 T for 1 R

Trade Offers

Traders will send signed trade offers to the off-chain clearinghouse. Periodically, the clearinghouse will send some of those signed offers to the smart contract, which will then execute the proposed trades.

There are two components in this system: an off-chain clearinghouse that puts trades together and a smart contract that executes those trades. In this post, I’ll focus on just the smart contract.

Escrowed Tokens

This system will rely on escrowed tokens from sellers to back their trade offers. I use our
escrow contract
to manage the escrow mechanics. The Escrow contract handles token deposits and withdrawals for traders as well as for the clearinghouse’s owner.

In addition to configuring escrow duration, the constructor also records the owner of the contract. Only the owner can submit signed trades to be executed.

Clearinghouse inherits from Signature, which provides routines for handling signed messages. Its source code is provided at the end of this post.

Validating a Sale Offer

The only difference between validating a signed message in this contract and the technique we described
previously
is the encoding of the signature. Previously, we used a single byte sequence containing the r, s, and v components, but now I’m going to keep those values separate. (I’m doing so to overcome a Solidity limitation, which I’ll point out when it’s relevant.)

Single Sale

A clearinghouse typically executes many trades simultaneously, and this contract will support that. But first I want to show how to execute a single signed trade offer. A single trade is between the seller and the clearinghouse:

functionexecuteOffer(addressseller,IERC20TokensellToken,uint256sellAmount,IERC20TokenreceiveToken,uint256receiveAmount,uint256timeLimit,uint256nonce,bytes32r,bytes32s,uint8v)public{require(msg.sender==owner,"Only the owner can execute offers.");validateOffer(seller,sellToken,sellAmount,receiveToken,receiveAmount,timeLimit,nonce,r,s,v);usedNonces[seller][nonce]=true;transfer(seller,owner,sellToken,sellAmount);transfer(owner,seller,receiveToken,receiveAmount);}

A few things to note about the single trade:

Only owner can submit a signed trade.

The offer must be validated.

The transfer function, which is inherited from Escrow, checks that there are sufficient tokens available and then transfers them.

Simultaneous Sales

The examples at the beginning of the post demonstrated the power of submitting simultaneous trades. This contract will support simultaneous trades in a single transaction. Interestingly, processing multiple trades is not as simple as just iterating over the trades and executing them sequentially.

An example will make it clear why sequential trading won’t work. Recall the example where X wants to trade 1 P for 1 Q and Y wants to do the reverse. A clearinghouse could broker such a trade because X can provide 1 P to Y, and Y can provide 1 Q to X. But, it would be impossible for the clearinghouse to complete either trade fully before starting the other trade because the clearinghouse might not own any P or Q tokens.

How would a real world clearinghouse execute this trade between X and Y? It would first get 1 P from X and then it would get 1 Q from Y. After that, it would distribute the Q to X and the P to Y. That is, it would execute the trades in two phases, first accumulating all the tokens being offered, and then distributing all the tokens being received.

This contract will validate all the offers, then gather all the tokens before distributing them:

functionexecuteOffers(address[]sellers,IERC20Token[]sellTokens,uint256[]sellAmounts,IERC20Token[]receiveTokens,uint256[]receiveAmounts,uint256[]timeLimits,uint256[]nonces,bytes32[]rs,bytes32[]ss,uint8[]vs)public{require(msg.sender==owner,"Only the owner can execute offers.");acceptOffers(sellers,sellTokens,sellAmounts,receiveTokens,receiveAmounts,timeLimits,nonces,rs,ss,vs);gatherOffers(sellers,sellTokens,sellAmounts);distributeOffers(sellers,receiveTokens,receiveAmounts);}

Note that the function takes many arrays of simple values, including the r, s, and v values. It would be more convenient to pass those all in arrays of structs or packed values, but Solidity doesn’t yet support that. That’s why they are unpacked.

The first phase validates all the offers and marks their nonces as used:

Clearinghouse Participation

The clearinghouse can participate in trading implicitly. If the accepted trades do not fully offset each other, it’s the clearinghouse contract that must make up the difference. This is what happens in the single-trade function above, but it can just as easily happen in the multiple-trade function as well.

Sometimes, accepted trades will work out in the clearinghouse’s favor. Suppose the following trades are offered to the clearinghouse:

X offers to trade 1 P for 1 Q

Y offers to trade 2 Q’s for 1 P

If the clearinghouse presents these two trades to the contract, both X and Y will get their respective tokens, but the clearinghouse will own the extra Q afterwards!

Why Escrow?

This contract could have been written without escrowed tokens. It could have relied instead on ERC20’s approve and transferFrom functions for transferring tokens between parties. This would have presented a vulnerability that I wanted to avoid: a transferFrom might fail if tokens became unavailable. If a transferFrom failed in a multiple-trade transaction, then all the trades would fail, and I wanted to avoid this possibility.

Summary

A “clearinghouse” combines 3rd-party trades, which may not have been acceptable individually.

A clearinghouse may act as a market maker and participate in trading.

Signed messages enable the clearinghouse to operate off-chain except for the final simultaneous trading.

Escrowed tokens enable the clearinghouse to be certain that trading will succeed.

The Complete Contract

clearinghouse.sol

pragma solidity^0.4.24;import"ierc20token.sol";import"signature.sol";import"escrow.sol";contractClearinghouseisEscrow,Signature{addressowner;constructor(uint256_escrowTime)Escrow(_escrowTime)public{owner=msg.sender;}mapping(address=>mapping(uint256=>bool))publicusedNonces;functionvalidateOffer(addressseller,IERC20TokensellToken,uint256sellAmount,IERC20TokenreceiveToken,uint256receiveAmount,uint256timeLimit,uint256nonce,bytes32r,bytes32s,uint8v)publicview{require(now<timeLimit,"Offer has expired.");require(!usedNonces[seller][nonce],"Duplicate nonce.");bytes32message=prefixed(keccak256(abi.encodePacked(address(this),sellToken,sellAmount,receiveToken,receiveAmount,timeLimit,nonce)));require(ecrecover(message,v,r,s)==seller,"Invalid signature.");}functionexecuteOffer(addressseller,IERC20TokensellToken,uint256sellAmount,IERC20TokenreceiveToken,uint256receiveAmount,uint256timeLimit,uint256nonce,bytes32r,bytes32s,uint8v)public{require(msg.sender==owner,"Only the owner can execute offers.");validateOffer(seller,sellToken,sellAmount,receiveToken,receiveAmount,timeLimit,nonce,r,s,v);usedNonces[seller][nonce]=true;transfer(seller,owner,sellToken,sellAmount);transfer(owner,seller,receiveToken,receiveAmount);}functionacceptOffers(address[]sellers,IERC20Token[]sellTokens,uint256[]sellAmounts,IERC20Token[]receiveTokens,uint256[]receiveAmounts,uint256[]timeLimits,uint256[]nonces,bytes32[]rs,bytes32[]ss,uint8[]vs)internal{for(uint256i=0;i<sellers.length;i++){validateOffer(sellers[i],sellTokens[i],sellAmounts[i],receiveTokens[i],receiveAmounts[i],timeLimits[i],nonces[i],rs[i],ss[i],vs[i]);usedNonces[sellers[i]][nonces[i]]=true;}}functiongatherOffers(address[]sellers,IERC20Token[]sellTokens,uint256[]sellAmounts)internal{for(uint256i=0;i<sellers.length;i++){transfer(sellers[i],owner,sellTokens[i],sellAmounts[i]);}}functiondistributeOffers(address[]sellers,IERC20Token[]receiveTokens,uint256[]receiveAmounts)internal{for(uint256i=0;i<sellers.length;i++){transfer(owner,sellers[i],receiveTokens[i],receiveAmounts[i]);}}functionexecuteOffers(address[]sellers,IERC20Token[]sellTokens,uint256[]sellAmounts,IERC20Token[]receiveTokens,uint256[]receiveAmounts,uint256[]timeLimits,uint256[]nonces,bytes32[]rs,bytes32[]ss,uint8[]vs)public{require(msg.sender==owner,"Only the owner can execute offers.");acceptOffers(sellers,sellTokens,sellAmounts,receiveTokens,receiveAmounts,timeLimits,nonces,rs,ss,vs);gatherOffers(sellers,sellTokens,sellAmounts);distributeOffers(sellers,receiveTokens,receiveAmounts);}}

signature.sol

pragma solidity^0.4.24;contractSignature{functionsplitSignature(bytessig)internalpurereturns(uint8,bytes32,bytes32){require(sig.length==65);bytes32r;bytes32s;uint8v;assembly{// first 32 bytes, after the length prefixr:=mload(add(sig,32))// second 32 bytess:=mload(add(sig,64))// final byte (first byte of the next 32 bytes)v:=byte(0,mload(add(sig,96)))}return(v,r,s);}functionrecoverSigner(bytes32message,bytessig)internalpurereturns(address){uint8v;bytes32r;bytes32s;(v,r,s)=splitSignature(sig);returnecrecover(message,v,r,s);}// Builds a prefixed hash to mimic the behavior of eth_sign.functionprefixed(bytes32hash)internalpurereturns(bytes32){returnkeccak256(abi.encodePacked("\x19Ethereum Signed Message:\n32",hash));}}