Merge pull request #4 from gnosis/more-docs

Described markets and LMSR

CONTRACTS.md

@@ -217,20 +217,46 @@ Returns if the outcome was challenged.
 
 Markets
 -------
+Markets provide liquidity for events: they buy and sell outcomes provided a fund. Market makers operate markets by controlling the pricing of outcomes given the current state of the market. Markets may be funded by the collateral associated with an event in order to obtain an initial cache of outcomes to sell. Beyond that, a market maker must decide on how to price outcomes.
+
 ### Abstract market
+An interface with which Gnosis markets must abide by
+
 #### fund(uint _funding)
+Allows to fund the market with collateral tokens converting them into outcome tokens
+
 #### close()
+Closes the market
+
 #### withdrawFees()
+Allows market creator to withdraw fees generated by trades
+
 #### buy(uint8 outcomeTokenIndex, uint outcomeTokenCount, uint maxCosts) returns (uint)
+Allows to buy outcome tokens from market maker as long as the price does not exceed a cap
+
 #### sell(uint8 outcomeTokenIndex, uint outcomeTokenCount, uint minProfits) returns (uint)
+Allows to sell outcome tokens to market maker as long as the price is greater than a specified minimum
+
 #### shortSell(uint8 outcomeTokenIndex, uint outcomeTokenCount, uint minProfits) returns (uint)
+Buys all outcomes, then sells all shares of selected outcome which were bought, keeping shares of all other outcome tokens, as long as selling the shares of the shorted outcome would result in a return more than a specified minimum
+
 #### calcMarketFee(uint outcomeTokenCosts) returns (uint)
+Calculates fee to be paid to market for transactions with specified cost.
 
 ### Default market
+Market contract which creates new markets with a flat percentage fee, where market closure transfers funds to the creator of the market
+
 #### DefaultMarket(address _creator, Event _eventContract, MarketMaker _marketMaker, uint _fee)
+Creates a market with a percentage fee for transactions and specified market maker
 
 ### Abstract market maker
+Defines the interface with which Gnosis market makers must abide.
+
 #### calcCost(Market market, uint8 outcomeTokenIndex, uint outcomeTokenCount) returns (uint)
+Determines cost to buy given number of outcome tokens in the current market state
+
 #### calcProfit(Market market, uint8 outcomeTokenIndex, uint outcomeTokenCount) returns (uint)
+Determines profit from selling given number of outcome tokens in the current market state
 
 ### LMSR market maker
+An automated market maker which uses the [logarithmic market scoring rule (LMSR)](http://mason.gmu.edu/~rhanson/mktscore.pdf). These markets react to the supply and demand of outcomes. For example, the prices of outcomes vary as their relative demands do. A key feature of an LMSR market maker is that a bounded loss can be specified for a market, implemented by setting a liquidity parameter `b = funding / log(number_of_outcomes)`. Note that the more funding a market gets, the larger the trade volume would have to be in order to move the price.