Home

Awesome

EtherEx

Build Status Dependency Status devDependency Status SlackIn Join the chat at https://gitter.im/etherex/etherex

Decentralized exchange built on Ethereum.

<img src="/frontend/screenshot.png" />

About

This repository contains the source code that runs the exchange on Ethereum as a set of contracts, along with the UI, tests, tools and documentation.

Components

Requirements

Installation

Start by cloning this repository.

git clone https://github.com/etherex/etherex.git

Development / testing

This will install pyethereum and ethereum-serpent if you don't already have those installed.

pip install -r dev_requirements.txt

Running tests

py.test -vvrs

Refer to Serpent and pyethereum for their respective usage.

UI development

You will need a working node.js setup (instructions) and globally installed grunt-cli (instructions).

cd frontend
npm install
grunt

And open http://localhost:8089/ in your browser.

Deployment

Requires a local client (Go or C++) with JSONRPC, Serpent and PyEPM

cd contracts
pyepm EtherEx.yaml

API

Operations

Methods (with serpent type definitions):

[
  price:[int256]:int256,
  buy:[int256,int256,int256]:int256,
  sell:[int256,int256,int256]:int256,
  trade:[int256,int256[]]:int256,
  cancel:[int256]:int256,
  deposit:[int256,int256]:int256,
  withdraw:[int256,int256]:int256,
  add_market:[int256,int256,int256,int256,int256,int256]:int256,
  get_market_id:[int256]:int256,
  get_market_id_by_name:[int256]:int256,
  get_last_market_id:[]:int256,
  get_market:[int256]:int256[],
  get_trade:[int256]:int256[],
  get_trade_ids:[int256]:int256[],
  get_sub_balance:[int256,int256]:int256[]
]

Price API

price(market_id)

Trade API

Add buy / sell trade

buy(amount, price, market_id)
sell(amount, price, market_id)

Trade

trade(max_amount, trade_ids)

Deposit

deposit(amount, market_id)

Withdraw

withdraw(amount, market_id)

Cancel trade

cancel(trade_id)

Adding a market

add_market(currency_name, contract_address, decimal_precision, price_denominator, minimum_total, category)

Getting a market's ID by contract address

get_market_id(contract_address)

Getting a market's ID by name

get_market_id_by_name(name)

Market names

Market names follow the "<currency name>/ETH" convention. When registering a new market, submit the currency name as a three or four letter uppercase identifier, ex.: "BOB" for BobCoin.

Contract address

The subcurrency contract address.

Decimal precision

The subcurrency's decimal precision as an integer.

Price denominator

Minimum trade total

When adding a subcurrency, set the minimum trade total high enough to make economic sense. A minimum of 10 ETH (1000000000000000000000 wei) is recommended.

Categories

1 = Subcurrencies
2 = Crypto-currencies
3 = Real-world assets
4 = Fiat currencies

EtherEx allows you to categorize your subcurrency into four main categories. Since everything is represented as subcurrencies, those categories are simply for convenience. If you have a DApp that has its own token, that would go in the regular subcurrency section 1. If your token represents a fiat currency redeemable at a gateway, add it to 4. If your token represents a real-world asset like gold or a car, add it to 3. For other crypto-currencies like BTC, also redeemable at a gateway, add it to 2.

Market IDs

1 = ETX/ETH

New market IDs will be created as DAO creators add their subcurrency to the exchange.

Subcurrency API

Subcurrency contracts need to support the Standardized Contract APIs (see current Draft), more specifically the approve, transferFrom and allowance methods for deposits, the transfer method for withdrawals and the balanceOf method for the UI to display the user's balance.

See the example ETX contract for a Serpent implementation, or a Standard Token in Solidity.

After registering the subcurrency using the add_market ABI call, the subcurrency will receive a market_id. You can retrieve the market ID with a call to get_market_id(contract_address).

Deposit support

IMPORTANT: The original deposit technique has been deprecated in favor of the Standardized Contract APIs

To support deposits to EtherEx, your subcurrency needs to implement the approve and transferFrom methods. The former allows a one-time transfer from the user's address by the exchange's contract, while the latter is called from the contract to effectively make that transfer when the user calls the exchange's new deposit method. This allows to securely send a subcurrency's tokens to the exchange's contract while updating the user's available balance at the exchange.

Withdrawal support

If your subcurrency's default method for transferring funds is also named transfer like the standard examples above, with the _to and _value parameters (in that order), then there is nothing else you need to do to support withdrawals from EtherEx to a user's address. Otherwise, you'll need to implement that same transfer method with those two parameters, and "translate" that method call to yours, calling your other method with those parameters, in the order they're expected. You may also have to use tx.origin instead of msg.sender in your method as the latter will return your contract's address.

def transfer(_to, _value):
    return(self.invertedtransfer(_value, _to))

Balance

Subcurrency contracts also need to implement a balanceOf method for the UI to display the user's balance in that contract (also called the subcurrency's wallet).

def balanceOf(_addr):
    return(self.balances[_addr].balance)

Accounts

TODO

Architecture

UX/UI

License

Released under the MIT License, see LICENSE file.