docs(x/ecocredit): update ecocredit spec

x/ecocredit/spec/01_concepts.md

@@ -53,6 +53,22 @@ Tradable credits are credits that can be transferred by the owner to another acc
 
 Retired credits are credits that cannot be transferred between accounts nor can they be unretired. Retired credits are equivalent to burned tokens with the exception that retired credits are actively tracked after being retired. Retiring a credit implies that the holder of a credit is “claiming” the credit as an offset. Credits can be retired upon issuance, retired upon transfer, and retired by the owner of the credits. The retirement location is required upon retirement.
 
+## Order Book
+
+The ecocredit module supports marketplace functionality using an order book model. The order book is an aggregate list of all the open buy and sell orders for ecosystem service credits. Depending on the preference of buyers and sellers, orders can be fully or partially executed and credits can be auto-retired or remain in a tradable state upon execution.
+
+### Sell Order
+
+A sell order is an order to sell ecosystem service credits. Each sell order has a unique ID that is auto-generated using a sequence table. A sell order stores the address of the owner of the credits being sold, the credit batch ID (denomination) of the credits being sold, the quantity of credits being sold, the asking price for each unit of the credit batch, and an option to enable/disable auto-retirement. Each credit unit of the credit batch will be sold for at least the asking price.
+
+### Buy Order
+
+A buy order is an order to buy ecosystem service credits. Like the sell order, each buy order has a unique ID that is auto-generated using a sequence table. A buy order can either be a direct buy order (an order against a specific sell order) or an indirect buy order (an order that can be filled by multiple sell orders that match a filter criteria). A buy order stores the selection (either the sell order id or the filter criteria), the quantity of credits to buy, the bid price for each unit of the credit batch(es), an option to enable/disable auto-retirement, and an option to enable/disable partial fills. A buy order can only successfully disable auto-retirement if the sell-order has disabled auto-retirement.
+
+## Ask Denom
+
+An "ask denom" is a denom that has been approved through a governance process as an accepted denom for listing ecosystem service credits. The "ask denom" includes the denom to allow (the base denom), the denom to display to the user, and an exponent that relates the denom to the display denom.
+
 ---
 
 ![Ecocredit Types](./assets/types.png)

x/ecocredit/spec/02_state.md

@@ -61,3 +61,43 @@ The `batchInfoTable` stores `BatchInfo`:
 `0x6 | []byte(BatchId) -> ProtocolBuffer(BatchInfo)`
 
 +++ https://github.com/regen-network/regen-ledger/blob/50eaceda5eabc5970effe491f0d58194852718c9/proto/regen/ecocredit/v1alpha1/types.proto#L33-L72
+
+## Sell Order Table
+
+The `sellOrderTable` stores `SellOrder`:
+
+`0x7 | []byte(OrderId) -> ProtocolBuffer(SellOrder)`
+
++++ https://github.com/regen-network/regen-ledger/blob/081ae071b159b397b4c10837804b69137295e3af/proto/regen/ecocredit/v1alpha1/types.proto#L122-L146
+
+#### Sell Order Sequence Table
+
+The `sellOrderTable` uses a persistent unique key generator called `Sequence`:
+
+`OrderId`: `0x8 | 0x1 -> BigEndian`
+
+The `0x1` is a fixed key to read/write data to the storage layer.
+
+## Buy Order Table
+
+The `buyOrderTable` stores `BuyOrder`:
+
+`0x9 | []byte(BuyOrderId) -> ProtocolBuffer(BuyOrder)`
+
++++ https://github.com/regen-network/regen-ledger/blob/081ae071b159b397b4c10837804b69137295e3af/proto/regen/ecocredit/v1alpha1/types.proto#L148-L196
+
+#### Buy Order Sequence Table
+
+The `buyOrderTable` uses a persistent unique key generator called `Sequence`:
+
+`BuyOrderId`: `0x10 | 0x1 -> BigEndian`
+
+The `0x1` is a fixed key to read/write data to the storage layer.
+
+## Ask Denom Table
+
+The `askDenomTable` stores `AskDenom`:
+
+`0x11 | []byte(Denom) -> ProtocolBuffer(AskDenom)`
+
++++ https://github.com/regen-network/regen-ledger/blob/081ae071b159b397b4c10837804b69137295e3af/proto/regen/ecocredit/v1alpha1/types.proto#L198-L210

x/ecocredit/spec/03_messages.md

@@ -40,7 +40,7 @@ In order to support use cases when credits are to be immediately retired upon is
 
 ## MsgSend
 
-Send sends tradable credits from one account to another account. Sent credits can either be tradable or retired on receipt.
+`Send` sends tradable credits from one account to another account. Sent credits can either be tradable or retired on receipt.
 
 +++ https://github.com/regen-network/regen-ledger/blob/50eaceda5eabc5970effe491f0d58194852718c9/proto/regen/ecocredit/v1alpha1/tx.proto#L122-L160
 
@@ -56,7 +56,7 @@ Send sends tradable credits from one account to another account. Sent credits ca
 
 ## MsgRetire
 
-Retire retires a specified number of credits in the holder's account.
+`Retire` retires a specified number of credits in the holder's account.
 
 +++ https://github.com/regen-network/regen-ledger/blob/50eaceda5eabc5970effe491f0d58194852718c9/proto/regen/ecocredit/v1alpha1/tx.proto#L165-L192
 
@@ -70,7 +70,7 @@ Retire retires a specified number of credits in the holder's account.
 
 ## MsgCancel
 
-Cancel removes a number of credits from the holder's account and also deducts them from the tradable supply, effectively cancelling their issuance on Regen Ledger.
+`Cancel` removes a number of credits from the holder's account and also deducts them from the tradable supply, effectively cancelling their issuance on Regen Ledger.
 
 +++ https://github.com/regen-network/regen-ledger/blob/50eaceda5eabc5970effe491f0d58194852718c9/proto/regen/ecocredit/v1alpha1/tx.proto#L198-L217
 
@@ -80,3 +80,51 @@ Cancel removes a number of credits from the holder's account and also deducts th
 - `credits` must not be empty
 - `batch_denom` must be a valid batch denomination
 - `amount` must be positive
+
+## MsgSell
+
+`Sell` creates one or more sell orders (i.e. sell orders are created in batches).
+
++++ https://github.com/regen-network/regen-ledger/blob/a70af9b4d5da6cf065eb23232ba8020769249688/proto/regen/ecocredit/v1alpha1/tx.proto#L292-L324
+
+### Validation:
+
+- `owner` must ba a valid address, and their signature must be present in the transaction
+- `batch_denom` must be a valid credit batch denom
+- `quantity` must be a positive decimal
+- `ask_price` must be a positive integer
+
+## MsgUpdateSellOrders
+
+`UpdateSellOrders` updates one or more sell orders (i.e. sell orders are updated in batches).
+
++++ https://github.com/regen-network/regen-ledger/blob/a70af9b4d5da6cf065eb23232ba8020769249688/proto/regen/ecocredit/v1alpha1/tx.proto#L333-L358
+
+### Validation:
+
+- `owner` must ba a valid address, and their signature must be present in the transaction
+- `new_quantity` must be a positive decimal
+- `new_ask_price` must be a positive integer
+
+## MsgBuy
+
+`MsgBuy` creates one or more buy orders (i.e. buy orders are created in batches).
+
++++ https://github.com/regen-network/regen-ledger/blob/a70af9b4d5da6cf065eb23232ba8020769249688/proto/regen/ecocredit/v1alpha1/tx.proto#L363-L391
+
+### Validation:
+
+- `buyer` must ba a valid address, and their signature must be present in the transaction
+- `quantity` must be a positive decimal
+- `bid_price` must be a positive integer
+
+## MsgAllowAskDenom
+
+`AllowAskDenom` is a governance operation which authorizes a new ask denom to be used in sell orders.
+
++++ https://github.com/regen-network/regen-ledger/blob/a70af9b4d5da6cf065eb23232ba8020769249688/proto/regen/ecocredit/v1alpha1/tx.proto#L430-L444
+
+### Validation:
+
+- `root_address` must be the address of the governance module
+- `denom` must be a valid denom