-
Notifications
You must be signed in to change notification settings - Fork 41
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add the spec docs for the exchange module (#1729)
* [1700]: make update-tocs to fix some existing TOCs. * [1700]: First crack at the exchange spec main README. * [1700]: First crack at the concepts spec doc. * [1700]: First crack at the state spec doc. * [1700]: Add empty place-holder files for the rest of the exchange spec docs. * [1700]: Initial write-up of messages spec doc. * [1700]: Events spec doc. * [1700]: Standardize the hr below the tocs. * [1700]: in the messages spec doc, include more sub-message content and add link references to those sections. * [1700]: Spec doc on the queries. * [1700]: Params spec doc. * [1700]: Turn lots of stuff into links and fix some inconsistent spacing. * [1700]: Reorder some market state entries. * [1700]: Add some missing blurbs under L1 headings. Remove the hrs above the L2 headings, and put a hr above each TOC. A L2 heading is underlined, so it looks weird when there's an hr above them too. * [1700]: Some updates to concepts from proof-reading them. Should be pretty solid now. * [1700]: Tweaks to state doc upon proof-reading. * [1700]: Proof reading of messages spec. * [1700]: Proof-read of the queries spec doc. * [1700]: Small tweak to the params spec doc upon proofreading. * Update x/exchange/spec/03_messages.md Co-authored-by: Jason Talis <[email protected]> --------- Co-authored-by: Jason Talis <[email protected]>
- Loading branch information
1 parent
a73ce33
commit 4aabad2
Showing
10 changed files
with
1,617 additions
and
6 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,283 @@ | ||
| # Exchange State | ||
|
|
||
| The Exchange module manages several things in state. | ||
|
|
||
| Big-endian ordering is used for all conversions between numbers and byte arrays. | ||
|
|
||
| --- | ||
| <!-- TOC --> | ||
| - [Params](#params) | ||
| - [Default Split](#default-split) | ||
| - [Specific Denom Split](#specific-denom-split) | ||
| - [Markets](#markets) | ||
| - [Market Create-Ask Flat Fee](#market-create-ask-flat-fee) | ||
| - [Market Create-Bid Flat Fee](#market-create-bid-flat-fee) | ||
| - [Market Seller Settlement Flat Fee](#market-seller-settlement-flat-fee) | ||
| - [Market Seller Settlement Ratio Fee](#market-seller-settlement-ratio-fee) | ||
| - [Market Buyer Settlement Flat Fee](#market-buyer-settlement-flat-fee) | ||
| - [Market Buyer Settlement Ratio Fee](#market-buyer-settlement-ratio-fee) | ||
| - [Market Inactive Indicator](#market-inactive-indicator) | ||
| - [Market User-Settle Indicator](#market-user-settle-indicator) | ||
| - [Market Permissions](#market-permissions) | ||
| - [Market Create-Ask Required Attributes](#market-create-ask-required-attributes) | ||
| - [Market Create-Bid Required Attributes](#market-create-bid-required-attributes) | ||
| - [Market Account](#market-account) | ||
| - [Market Details](#market-details) | ||
| - [Known Market ID](#known-market-id) | ||
| - [Last Market ID](#last-market-id) | ||
| - [Orders](#orders) | ||
| - [Ask Orders](#ask-orders) | ||
| - [Bid Orders](#bid-orders) | ||
| - [Last Order ID](#last-order-id) | ||
| - [Indexes](#indexes) | ||
| - [Market to Order](#market-to-order) | ||
| - [Owner Address to Order](#owner-address-to-order) | ||
| - [Asset Denom to Order](#asset-denom-to-order) | ||
| - [Market External ID to Order](#market-external-id-to-order) | ||
|
|
||
|
|
||
| ## Params | ||
|
|
||
| All params entries start with the type byte `0x00` followed by a string identifying the entry type. | ||
|
|
||
| Each `<split>` is stored as a `uint16` (2 bytes) in big-endian order. | ||
|
|
||
| The byte `0x1E` is used in a few places as a record separator. | ||
|
|
||
| See also: [Params](06_params.md#params). | ||
|
|
||
|
|
||
| ### Default Split | ||
|
|
||
| The default split defines the split amount (in basis points) the exchange receives of fees when there is not an applicable specific denom split. | ||
|
|
||
| * Key:`0x00 | "split" (5 bytes)` | ||
| * Value: `<split (2 bytes)>` | ||
|
|
||
|
|
||
| ### Specific Denom Split | ||
|
|
||
| A specific denom split is a split amount (in basis points) the exchange receives of fees for fees paid in a specific denom. | ||
|
|
||
| * Key: `0x00 | "split" (5 bytes) | <denom (string)>` | ||
| * Value: `<split (2 bytes)>` | ||
|
|
||
| See also: [DenomSplit](06_params.md#denomsplit). | ||
|
|
||
|
|
||
| ## Markets | ||
|
|
||
| Each aspect of a market is stored separately for specific lookup. | ||
|
|
||
| Each `<market id>` is a `uint32` (4 bytes) in big-endian order. | ||
|
|
||
| Most aspects of a market have keys that start with the type byte `0x01`, followed by the `<market id>` then another type byte. | ||
|
|
||
| See also: [Market](03_messages.md#market). | ||
|
|
||
|
|
||
| ### Market Create-Ask Flat Fee | ||
|
|
||
| One entry per configured denom. | ||
|
|
||
| * Key: `0x01 | <market id (4 bytes)> | 0x00 | <denom (string)>` | ||
| * Value: `<amount (string)>` | ||
|
|
||
|
|
||
| ### Market Create-Bid Flat Fee | ||
|
|
||
| One entry per configured denom. | ||
|
|
||
| * Key: `0x01 | <market id (4 bytes)> | 0x01 | <denom (string)>` | ||
| * Value: `<amount (string)>` | ||
|
|
||
|
|
||
| ### Market Seller Settlement Flat Fee | ||
|
|
||
| One entry per configured denom. | ||
|
|
||
| * Key: `0x01 | <market id (4 bytes)> | 0x02 | <denom (string)>` | ||
| * Value: `<amount (string)>` | ||
|
|
||
|
|
||
| ### Market Seller Settlement Ratio Fee | ||
|
|
||
| One entry per configured price:fee denom pair. | ||
|
|
||
| * Key: `0x01 | <market id (4 bytes)> | 0x03 | <price denom (string)> | 0x1E | <fee denom (string)>` | ||
| * Value: `<price amount (string)> | 0x1E | <fee amount (string)>` | ||
|
|
||
| See also: [FeeRatio](03_messages.md#feeratio). | ||
|
|
||
|
|
||
| ### Market Buyer Settlement Flat Fee | ||
|
|
||
| One entry per configured denom. | ||
|
|
||
| * Key: `0x01 | <market id (4 bytes)> | 0x04 | <denom (string)>` | ||
| * Value: `<amount (string)>` | ||
|
|
||
|
|
||
| ### Market Buyer Settlement Ratio Fee | ||
|
|
||
| One entry per configured price:fee denom pair. | ||
|
|
||
| * Key: `0x01 | <market id (4 bytes)> | 0x05 | <price denom (string)> | 0x1E | <fee denom (string)>` | ||
| * Value: `<price amount (string)> | 0x1E | <fee amount (string)>` | ||
|
|
||
| See also: [FeeRatio](03_messages.md#feeratio). | ||
|
|
||
|
|
||
| ### Market Inactive Indicator | ||
|
|
||
| When a market has `accepting_orders = false`, this state entry will exist. | ||
| When it has `accepting_orders = true`, this entry will not exist. | ||
|
|
||
| * Key: `0x01 | <market id (4 bytes)> | 0x06` | ||
| * Value: `<nil (0 bytes)>` | ||
|
|
||
|
|
||
| ### Market User-Settle Indicator | ||
|
|
||
| When a market has `allow_user_settlement = true`, this state entry will exist. | ||
| When it has `allow_user_settlement = false`, this entry will not exist. | ||
|
|
||
| * Key: `0x01 | <market id (4 bytes)> | 0x07` | ||
| * Value: `<nil (0 bytes)>` | ||
|
|
||
|
|
||
| ### Market Permissions | ||
|
|
||
| When an address has a given permission in a market, the following entry will exist. | ||
|
|
||
| * Key: `0x01 | <market id (4 bytes)> | 0x08 | <addr len (1 byte)> | <addr> | <permission type byte (1 byte)>` | ||
| * Value: `<nil (0 bytes)>` | ||
|
|
||
| The `<permission type byte>` is a single byte as `uint8` with the same values as the enum entries, e.g. `PERMISSION_CANCEL` is `0x03`. | ||
|
|
||
| See also: [AccessGrant](03_messages.md#accessgrant) and [Permission](03_messages.md#permission). | ||
|
|
||
|
|
||
| ### Market Create-Ask Required Attributes | ||
|
|
||
| * Key: `0x01 | <market id (4 bytes)> | 0x09 | 0x00` | ||
| * Value: `<list of strings separated by 0x1E>` | ||
|
|
||
|
|
||
| ### Market Create-Bid Required Attributes | ||
|
|
||
| * Key: `0x01 | <market id (4 bytes)> | 0x09 | 0x01` | ||
| * Value: `<list of strings separated by 0x1E>` | ||
|
|
||
|
|
||
| ### Market Account | ||
|
|
||
| Each market has an associated `MarketAccount` with an address derived from the `market_id`. | ||
| Each `MarketAccount` is stored using the `Accounts` module. | ||
|
|
||
| +++ https://github.com/provenance-io/provenance/blob/v1.17.0/proto/provenance/exchange/v1/market.proto#L14-L26 | ||
|
|
||
|
|
||
| ### Market Details | ||
|
|
||
| The [MarketDetails](03_messages.md#marketdetails) are stored as part of the `MarketAccount` (in the `x/auth` module). | ||
|
|
||
|
|
||
| ### Known Market ID | ||
|
|
||
| These entries are used to indicate that a given market exists. | ||
|
|
||
| * Key: `0x07 | <market id (4 bytes)>` | ||
| * Value: `<nil (0 bytes)>` | ||
|
|
||
|
|
||
| ### Last Market ID | ||
|
|
||
| This indicates the last market-id that was auto-selected for use. | ||
|
|
||
| When a `MsgGovCreateMarketRequest` is processed that has a `market_id` of `0` (zero), the next available market id is auto selected. | ||
| Starting with the number after what's in this state entry, each market id is sequentially checked until an available one is found. | ||
| The new market gets that id, then this entry is then updated to indicate what that was. | ||
|
|
||
| * Key: `0x06` | ||
| * Value: `<market id (4 bytes)>` | ||
|
|
||
| When a `MsgGovCreateMarketRequest` is processed that has a non-zero `market_id`, this entry is not considered or altered. | ||
|
|
||
|
|
||
| ## Orders | ||
|
|
||
| Each `<order id>` is a `uint64` (8 bytes) in big-endian order. | ||
|
|
||
| Orders are stored using the following format: | ||
|
|
||
| * Key: `0x02 | <order id (8 bytes)>` | ||
| * Value `<order type byte> | protobuf(order type)` | ||
|
|
||
| The `<order type byte>` has these possible values: | ||
| * `0x00` => Ask Order | ||
| * `0x01` => Bid Order | ||
|
|
||
|
|
||
| ### Ask Orders | ||
|
|
||
| * Key: `0x02 | <order id (8 bytes)>` | ||
| * Value: `0x00 | protobuf(AskOrder)` | ||
|
|
||
| See also: [AskOrder](03_messages.md#askorder). | ||
|
|
||
|
|
||
| ### Bid Orders | ||
|
|
||
| * Key: `0x02 | <order id (8 bytes)>` | ||
| * Value: `0x01 | protobuf(BidOrder)` | ||
|
|
||
| See also: [BidOrder](03_messages.md#bidorder). | ||
|
|
||
|
|
||
| ### Last Order ID | ||
|
|
||
| Whenever an order is created, this value is looked up and incremented to get the new order's id. | ||
| Then this entry is updated to reflect the new order. | ||
|
|
||
| * Key: `0x08` | ||
| * Value: `<order id (8 bytes)>` | ||
|
|
||
|
|
||
| ## Indexes | ||
|
|
||
| Several index entries are maintained to help facilitate look-ups. | ||
|
|
||
| The `<order type byte>` values are the same as those described in [Orders](#orders). | ||
|
|
||
|
|
||
| ### Market to Order | ||
|
|
||
| This index can be used to find orders in a given market. | ||
|
|
||
| * Key: `0x03 | <market id (4 bytes)> | <order id (8 bytes)>` | ||
| * Value: `<order type byte (1 byte)>` | ||
|
|
||
|
|
||
| ### Owner Address to Order | ||
|
|
||
| This index can be used to find orders with a given buyer or seller. | ||
|
|
||
| * Key: `0x04 | <addr len (1 byte)> | <addr> | <order id (8 bytes)>` | ||
| * Value: `<order type byte (1 byte)>` | ||
|
|
||
|
|
||
| ### Asset Denom to Order | ||
|
|
||
| This index can be used to find orders involving a given `assets` denom. | ||
|
|
||
| * Key: `0x05 | <asset denom> | <order id (8 bytes)>` | ||
| * Value: `<order type byte (1 byte)>` | ||
|
|
||
|
|
||
| ### Market External ID to Order | ||
|
|
||
| This index is used to look up orders by their market and external id. | ||
|
|
||
| * Key: `0x09 | <market id (4 bytes)> | <external id (string)>` | ||
| * Value: `<order id (8 bytes)>` |
Oops, something went wrong.