For Review: 'Intrinsically Tradable Tokens' (ITT's) are their own exchange

o0ragman0o

For Review: 'Intrinsically Tradable Tokens' (ITT's) are their own exchange

Introducing Intrinsically Tradable Tokens, ERC20 compliant tokens in which you can buy and sell directly from the contract.

Ropsten 0xa9e001bebe4b281f7229b0305f553ab3c511fef5

Live 0xa15c784319fa96d3E36cFE97fbadD89Ec704A8dc

ITT's extend the ERC20 API with:

buy(uint price, uint amount, bool make)
sell(uint price, uint amount, bool make)
cancel(uint price)
withdraw(uint ether)

and other ancillary exchange state getters (see Github repo for full API) such as :

etherBalanceOf(address holder)
getBook()
getOrdersOf(address trader)
spread(bool side)

The intrinsic exchange functionality works on a FIFO matching maker/taker algorithm. A new order may be iteratively filled by multiple make orders on the book or if unfilled, can be put on the book itself as a make order.

ITT demo contracts have been deployed on the Ropsten test chain on which a number of Buy and Sell orders have already been placed for you to play with. The demo ITT and future, more functional ITT's can be can be interacted with using the front end DAPP ITTDesk.

Use Cases

This demo ITT serves to demonstrate the exchange functionality of a basic ITT contract and does not have much intrinsic value in the token itself beyond being a purely speculative coin.

The ITT API and base contract are open source and offered to the community in order to extend or attach value adding functionality to the token side.

As is, crowd funding and token sales become as trivial by simply placing ask orders (see Self Funding below).

Better still would be to extended ITT functionality to make a 'Payable ITT' which becomes a simple but highly versatile pay to an unknown many mechanism which can distribute payments according to proportional holdings. Such holdings might represent shareholders, a rewards system or perhaps be used to fund and manage a DAO's project funds. (I do have a Payable ITT but will not likely release it until the community has confidence in the basic ITT contract)

Other value adding developments might be to couple ITT's to fiat currencies for truly low friction decentralised forex.

Current State of Development

As deployed, the ITT Demo contract is yet to undergo extensive testing and formal verification. It appears to work as intended (unless compiled with 0.4.5+commit.b318366e! My first launch attempt drove me crazy until that bug was announced). The contract on both chains have been verified on etherscan.io etherscan.io.

The ITTDesk app is very much in alpha release, minimalist and clunky in it's function. It is written on Meteor and attempts to use Mist styling and elements. Probably best just to clone the repo and run it up in Meteor at this stage. It features intelligent ask/bid/buy/sell trade buttons to assisting in validating user inputs in the order fields.

I am not an experienced web developer, so feed back, suggestions, criticisms are most welcome. In particular, I've not been able to work up the filters without causing browser timeout.

How does it work?

The order book utilises a mapping of 'Circular Linked Lists (CLL)' from the LibCLLi library to order and lookup the booked prices and iterate the FIFO's at each price.
Each FIFO in the mapping is keyed by its price and holds all the addresses of traders who have made orders at that price. A trader can only have a single order at any particular price. An attempt to book another order at the same price will adjust and put the order at the back of the FIFO queue. This prevents FIFO hogging in which a trader might otherwise starve other orders by continually topping up their own.

A second trivial mapping holds the actual order amounts. It is keyed by a SHA3 hash of the trader's address with the price of the order (and is actually what limits the trader to one price, one order).

The CLL's heads are static at mapping key '0'. To use as a FIFO, nodes are simply inserted previous to the head and removed from next to the head. A FILO (stack) can be implemented with equal simplicity.

In the case of the price list, the links either side of the head are the highestBid (previous) and lowestAsk (next) making the head node itself the market spread. The price list is artificially bound to minimum (uint 1) and maximum (uint 2**128) prices. New price nodes are inserted relative to the head (spread) after iterating through an order search.

Looping operations in Smart Contracts can be bug prone and costly, especially with state mutations in each loop as in the ITT's matching algorithm. For this reason, the order matching loop is dynamically limited by the gas supply from msg.gas and will exit with a partially filled order rather than throw it. The remainder does not get put on the book as a make order as it would cause a bid/ask collision at that price. Because of this looping, gas cannot be estimated and it is up to the trader to consider the costs and adjust the amount of gas prior to ordering.

The matching algorithm is not without architectural efficiency however which almost halves the number to calls to STORE by virtualising (caching to memory) the taker's state variables prior to the matching loop and writing back to store once the matching and making operations exit.

Security and Resilience

ITT's hold ether balances and therefore are presumed to be targeted by hacking attempts. A number of security features and practices have therefore been programmed into the contract.

All external or payable state mutating functions are 'reentry protected' by a mutex which is set and cleared in the internal function safeSend(), which is called only by the public function withdraw(). This practice ensures a single entry and exit.

The architecture also separates entry validation logic and parameter preparation which is kept in the external/payable functions, from state mutation logic which is kept in the internal functions. This allows for a secure, flexible, inheritable API/interface layer from which to extend the contract while keeping the basic ITT internal functionality the same.

In the ITT Demo, the default function is unimplemented and therefore throws if payments are sent to anything other than the payable buy() function.

Attention must also be drawn to some rather unconventional use of uint math in the matching loop. Elsewhere, the contract uses explicitly safe maths functions, however the nature of an exchange function requires numerous inverse and signed integer operations. It was found that casting between int and uint became an onerous task with potentially unpredictable outcome and a design decision was made to simply treat uint as signed within the matching loop. In this case -1 == 2**256-1 and is used in multiplication to change the sign of trade amounts during matching.

In light of the signed uint adoption, a further mathematical constraint was placed on the maximum price and amount allowed being 2**128 which prevents any multiplication overflows.

Testing

Given that this contract is Proof of Concept deployment primarily for public review, it should be considered insecure. It has been tested for functionality but no exhaustive testing regime or formal verification has been put against it. It is undeniably a big ugly contract with complex logic and so should be viewed with suspicion.

Interacting with the Live contract is thereby at your own risk!

Self Funding

Being the deploying owner of this Demo ITT, I am granted the full balance of tokens and have placed both ask and bid orders as examples. Purchasing my Ask orders on the Live chain does transfer real ether to my balance and so I am trailing this as a channel for funding my development efforts rather than chasing bounties, competitions, donations, (a real job) or what have you. If you buy tokens here, you could consider it as a much appreciated donation which you might also be able to return a speculative profit from! It would certainly make my life easier.

Who Am I?

My name is Darryl Morris AKA o0ragman0o. I'm an independent (and some what isolated) Australian Ethereum developer. Though fairly quite, I've been following Ethereum developments since November 2014 (PoC 6) and have been small time mining since Olympic, though not now with expensive Australian electricity. I am best known on forum.ethereum.org where I am a mod. I've been crypto aware since 2009 when I tried bitcoin in it's infancy. I got 71/70 marks for Griff Green's notorious 'DAO Ninja' homework though obviously needed 72 to recognise the complex of vulnerabilities in that code!

My interests are in developing delegative democracy technologies with which to render all politicians obsolete (particularly ones beginning with 'T'). To that end I've developed the ITT contract as a funding component of a democracy DAO framework I call 'Ethenian DAO'.

Looking for interested collaborators.

Cheers
Darryl