Torus CAD updates

Author: mikera

cad/030_torus/README.md

@@ -8,9 +8,9 @@ Torus is a decentralised exchange (DEX) built on Convex. It is an open source ac
 
 ### Torus actor
 
-The Torus actor is the actor that manages all Torus DEX markets and provides user functionality.
+The Torus actor manages all Torus DEX markets and provides user functionality.
 
-Use of the library is typically achieved by importing the Torus actor as a library: 
+Users typically import the Torus actor as a library to make Torus functions available in their environment: 
 
 ```clojure
 (import exchange.torus :as torus)
@@ -40,13 +40,59 @@ Subsequently, the address of a market can be accessed with the `get-market` func
 
 If no market exists for a fungible asset, `get-market` returns `nil`.
 
-### Convex Coin Liquidity
+### Trades
 
-Each active Torus market MUST contain Convex Coins in the liquidity pool, of equal value to the CAD29 fungible token being traded.
+Any user may trade on a Torus market.
+
+```clojure
+;; Assume a CAD token identified by TOKEN
+
+;; Buy a 100 token quantity of a token
+(torus/buy-tokens TOKEN 100)
+
+;; Sell 100 tokens
+(torus/sell-tokens TOKEN 100)
+
+;; Buy 1000 CVX using the token
+(torus/buy-cvx TOKEN 1000)
+
+;; Sell 1000 CVX, receiving the token
+(torus/sell-cvx TOKEN 1000)
+```
+
+It is also possible to do swaps between any two tokens. These are atomic swaps that execute a Torus trade on both underlying markets.
+
+```clojure
+;; Assume we have a second token named USD
+
+;; Buy 200 TOKEN using USD
+(torus/buy TOKEN 200 USD)
+
+;; Sell 300 TOKEN and receive USD
+(torus/sell TOKEN 300 USD)
+
+```
+
+Trades will fail if any of the following are true:
+- An attempt is made to buy or sell a negative quantity
+- The liquidity pool has insufficient liquidity to complete the trade
+- The user has insufficient funds (CVX or token) to complete the trade
+
+### Liquidity Pool
+
+Each Torus market holds a liquidity pool of two assets:
+- Convex Coins
+- The CAD29 fungible token that the market represents
+
+Each active Torus market MUST have a positive Convex Coins in the liquidity pool.
+
+Each active Torus market MUST own a positive balance of the CAD29 fungible token being traded.
+
+The Torus market assumes the two asset quantities have equal value.
 
 We use Convex Coins as the common pairing for each fungible token because:
 - This enables swaps between any two CAD29 tokens with just two swaps, avoiding the need to create a market for every possible fungible token pair.
-- Convex Coins generally make sense to hold as an asset for ecosystem participants
+- Convex Coins generally make sense to hold as a common asset for ecosystem participants
 - It provides an additional opportunity to earn a return on Convex Coins
 
 ### Adding and withdrawing liquidity
@@ -63,15 +109,21 @@ A prospective liquidity provide MAY add liquidity to a market at any time with t
 (torus/add-liquidity token-id token-quantity)
 ```
 
-If successful, `add-liquidity` will return with a integer equal to the number of liquidity shares gained by the liquidity provider.
+If successful, `add-liquidity` will return an integer equal to the number of liquidity shares gained by the liquidity provider.
 
 The attempt to add liquidity will fail if the user has insufficient Convex coins or tokens to provide the liquidity.
 
 If the market does not already exist, one will be created as if `create-market` was used.
 
 
 
-### TODO more specification
+### Torus Market SPI
+
+The Torus market SPI is usually not directly accessed by users: Torus functionality should be accessed by the `exchange.torus` library.
+
+A Torus market MUST implement a CAD29 fungible token SPI so that its liquidity share function as a fungible token.
+
+The Torus market SPI MAY change due to updates of Torus