spec: update roundup

1. Describe new trade suspension messaging
2. Describe administrative API
3. Rewrite intro section. Combine "Abstract" and "Introduction". Shortened and more focused. 
4. Full table of contents in the spec readme
5. Various typos and drift corrections.

dex/msgjson/types.go

@@ -371,7 +371,7 @@ type Match struct {
 	Signature
 	OrderID    Bytes  `json:"orderid"`
 	MatchID    Bytes  `json:"matchid"`
-	Quantity   uint64 `json:"quantity"`
+	Quantity   uint64 `json:"qty"`
 	Rate       uint64 `json:"rate"`
 	Address    string `json:"address"`
 	ServerTime uint64 `json:"tserver"`
@@ -662,7 +662,7 @@ type OrderNote struct {
 // limit or market order.
 type TradeNote struct {
 	Side     uint8  `json:"side,omitempty"`
-	Quantity uint64 `json:"osize,omitempty"`
+	Quantity uint64 `json:"qty,omitempty"`
 	Rate     uint64 `json:"rate,omitempty"`
 	TiF      uint8  `json:"tif,omitempty"`
 	Time     uint64 `json:"time,omitempty"`

spec/README.mediawiki

@@ -1,124 +1,123 @@
-=Decred DEX=
-
-This is the repository for the Decred Distributed Exchange (DEX), for which this
-document provides the '''DRAFT''' specification.
+=Decred DEX Specification=
 
 __TOC__
 
-==Abstract==
-
-We propose here a decentralized, non-custodial, trustless, and intermediary-free
-cryptocurrency exchange platform.
-
-The primary service provided by the decentralized exchange (DEX) is to match
-clients who would like to trade an asset of one type for an asset of another
-type.
-Trades are facilitated by a trustless atomic swap negotiation process carried
-out with all the cryptographic security guarantees of the respective blockchains.
-
-A custom order matching procedure is offered to mitigate common abusive trading
-patterns associated with high-frequency trading (HFT) algorithms and other
-bot-driven trading.
-Elimination of per-trade fees disincentivizes deceptive bookkeeping practices
-commonly observed in centralized exchanges.
+==Introduction==
 
-To encourage open and active development, descriptions of critical protocol
-components and a full client-server API definition are provided.
+Decred DEX is a decentralized, non-custodial, trustless, and intermediary-free
+cryptocurrency exchange platform. Decred DEX aims to solve a number of issues
+with existing systems of exchange.
 
-==Introduction==
+Currently, the majority of cryptocurrency trading is performed via centralized,
+custodial exchanges.
+These exchanges have filled an important role in the blockchain ecosystem, but
+are in many ways antithetical to the spirit of blockchain.
+Blockchain is decentralized, trustless, and enables self-custody, but when a
+user must send their coin to a third party in order to trade, all of those
+benefits are lost.
 
-Existing cryptocurrency exchange platforms fall into 4 overlapping categories:
-custodial corporate entities, services, tokens, and blockchains.
-The vast majority of cryptocurrency trading is currently performed via
-centralized, custodial exchanges.
-Since trades at these exchanges take place off-chain, they generally settle
-instantly to make funds available for further trading.
-This is a nice feature, but it practically guarantees that the market
-will be a target of HFT and algorithmic traders, which can be unpredictable and
-malicious.
-Additionally, such exchanges earn revenue by collecting trading fees.
-Such a model creates incentives for an exchange to artificially inflate their
-volume by wash trading [1].
-By one study, it has been estimated that more than 95% of reported exchange
-volume is faked
-[https://www.sec.gov/comments/sr-nysearca-2019-01/srnysearca201901-5164833-183434.pdf [2]].
-
-Several DEX projects have been created to address some of these issues by
+Several projects have attempted to address this misalignment by
 replacing the exchange with a blockchain or a token, and they have met with
 varying degrees of success.
 While they remove the trusted third party (TTP), they insert their own products
-as a means to capture the trading fees, which replaces the TTP friction with a
+as a means to capture trading fees, which replaces the TTP friction with a
 new platform friction.
-The simple act of collecting trading fees serves to act as an incentive to
-centralize on a given solution, which runs counter to a system of open voluntary
-exchange.
-While a chain or token serves to remove the TTP, it also creates challenges with
-order matching, which typically occurs via the intermediate chain or token.
-
-The DEX described in this document is based on atomic swaps [https://github.com/decred/atomicswap [3]], signed and
-transmitted by the clients. Thus, the exchange of funds is trustless and secure.
-The purpose of the DEX is to facilitate such peer-to-peer trades, while
-disincentivizing manipulative or abusive trading patterns, and utilizing an
-independently verifiable order matching algorithm that is difficult to game by
-traders and operators alike.
+
+A more robust solution is based on atomic swap technology [https://github.com/decred/atomicswap [2]], 
+which enables trustless exchange directly between wallets. 
+Until recently, few blockchains supported atomic swaps, but the past few years
+have seen widespread adoption, and such an exchange is now possible.
+
+Decred DEX is the first exchange built on atomic swaps that doesn't collect
+trading fees. The primary service offered by DEX is to match traders through a
+familiar interface based on markets and orders. Decred DEX's novel matching
+algorithm disincintevizes manipulative, abusive trading practices commonly seen
+on centralized exchanges. The epoch-based match cycle is difficult to game by
+the client, while for the server, cryptographic order commitments make
+censorship and unfair matching difficult.
 
 While trades are fully trustless, steps are taken to discourage malicious
 clients from hindering normal trade activity.
-Registered clients are bound by the
+All clients pay a non-refundable registration fee.
+Registered clients are then bound to the
 [[community.mediawiki|rules of community conduct]], violation of which typically
-results in loss of trading privileges.
-Serious violations may result in a permanent ban, in which case the affected user
-must pay another registration fee to continue using the DEX.
-
-The following list of non-negotiable, fundamental, DEX properties served as a
-basis for design.
-
-# Non-custodial. Assets must be traded directly between clients, without the exchange being in control of assets at any time.
-
-# Intermediary-free. Trades must be executed in a secure and trustless manner.
+results in loss of trading privileges up to and including a permanent ban.
 
-# Resistant to malicious or manipulative trading. Deliberately disruptive behavior should be disincentivized, and volume manipulation mitigated by pseudo-random epoch-based order matching.
+In the interest of maintaining active, open-source, community-driven
+development, this specification document describes the protocols necessary for
+implementation of both DEX clients and DEX servers.
 
-==Sections==
+==Contents==
 
-The remainder of this document details the design of the proposed DEX.
+The remaining content details the Decred DEX protocol.
 It is intended as a first resource when implementing servers and clients.
 Continuing client-server interoperability will likely depend on subtle aspects
-of the specification laid out in this document, especially the following
-critical sections.
+of the specification laid out in this document.
 
 '''[1] [[comm.mediawiki|Communication Protocols]]''' describes the
 messaging protocols and communication layer technologies that are to be used
 for the DEX API.
 
+* [[comm.mediawiki#WebSockets|WebSockets]]
 * [[comm.mediawiki/#Encoding|Data Encodings]]
+** [[comm.mediawiki/#Timestamps|Timestamps]]
+** [[comm.mediawiki/#Rate_Encoding|Rate Encoding]]
+** [[comm.mediawiki/#Coin_ID|Coin ID]]
 * [[comm.mediawiki/#Message_Protocol|Message Protocol]]
 * [[comm.mediawiki/#Session_Authentication|Session Authentication]]
+* [[comm.mediawiki/#HTTP|HTTP]]
 
 '''[2] [[fundamentals.mediawiki|Distributed Exchange Design Fundamentals]]'''
 describes the notable design aspects that facilitate an exchange service with
 the features described above.
 
 * [[fundamentals.mediawiki/#Exchange_Variables|Exchange Variables]]
+** [[fundamentals.mediawiki/#Global_Variables|Global Variables]]
+** [[fundamentals.mediawiki/#Asset_Variables|Asset Variables]]
+** [[fundamentals.mediawiki/#Market_Variables|Market Variables]]
+** [[fundamentals.mediawiki/#Configuration_Data_Request|Configuration Data Request]]
 * [[fundamentals.mediawiki/#Epochbased_Order_Matching|Epoch-based Order Matching]]
+** [[fundamentals.mediawiki/#Epoch_Time|Epoch Time]]
+** [[fundamentals.mediawiki/#Pseudorandom_Order_Matching|Pseudorandom Order Matching]]
 * [[fundamentals.mediawiki/#Identities_based_on_Public_Key_Infrastructure_PKI_Key_Pairs|Identification]]
+* [[fundamentals.mediawiki/#Blockchain_Interaction|Blockchain Interaction]]
+* [[fundamentals.mediawiki/#Adding_New_Assets|Adding New Assets]]
 
 '''[3] [[admin.mediawiki|Distributed Exchange Administration]]''' describes
 the tasks required to administer the exchange.
 
+* [[admin.mediawiki/#Exchange_Variables|Exchange Variables]]
+* [[admin.mediawiki/#Perasset_Variables|Per-asset Variables]]
+* [[admin.mediawiki/#Administration_API|Administration API]]
+
 '''[4] [[accounts.mediawiki|Client Accounts]]''' details account creation.
 
+* [[accounts.mediawiki/#Step_1_Registration|Registration]]
+* [[accounts.mediawiki/#Step_2_Fee_Notification|Fee Notification]]
+
 '''[5] [[orders.mediawiki|Client Order Management]]''' details the different
 order types and the client/server workflows required to synchronize the order
 book and place orders.
 
 * [[orders.mediawiki/#Connection_Persistence|Connection Persistence]]
 * [[orders.mediawiki/#Order_Book_Subscriptions|Order Book Subscriptions]]
+* [[orders.mediawiki/#Order_Preparation|Order Preparation]]
+** [[orders.mediawiki/#Calculating_Transaction_Fees|Calculating Transaction Fees]]
+** [[orders.mediawiki/#Coin_Preparation|Coin Preparation]]
+** [[orders.mediawiki/#Order_Commitment|Order Commitment]]
+** [[orders.mediawiki/#Order_Signing|Order Signing]]
+** [[orders.mediawiki/#Order_ID|Order ID]]
 * [[orders.mediawiki/#Order_Types|Order Types]]
+** [[orders.mediawiki/#Limit_Order|Limit Order]]
+** [[orders.mediawiki/#Market_Order|Market Order]]
+*** [[orders.mediawiki/#Market_Buy_Orders|Market Buy Orders]]
+** [[orders.mediawiki/#Cancel_Order|Cancel Order]]
 * [[orders.mediawiki/#Preimage_Reveal|Preimage Handling]]
+* [[orders.mediawiki/#Match_Revocation|Match Revocation]]
 * [[orders.mediawiki/#Match_negotiation|Match Negotiation]]
+* [[orders.mediawiki/#Trade_Suspension|Trade Suspension]]
 
-'''[6] [[api.mediawiki| Data API]]''' defines http and websocket APIs to browse
+'''[6] [[api.mediawiki| Data API]]''' defines http and WebSocket APIs to browse
 trade history.
 
 '''[7] [[atomic.mediawiki|Atomic Settlement]]''' walks through the settlement
@@ -127,5 +126,8 @@ process with a couple of examples to provide a high-level overview.
 '''[8] [[community.mediawiki|Community Conduct]]''' describes the system of rules
 to which clients interacting with the DEX must adhere.
 
+* [[community.mediawiki/#Rules_of_Community_Conduct|Rules of Community Conduct]]
+* [[community.mediawiki/#Penalties|Penalties]]
+
 '''[9] [[references.mediawiki|References]]''' lists references used in the development
 of the specification.

spec/accounts.mediawiki

@@ -13,7 +13,7 @@ string in API messages.
 
 ==Step 1: Registration==
 
-The user creates a websocket connection and sends their
+The user creates a WebSocket connection and sends their
 [[fundamentals.mediawiki/#Identities_based_on_Public_Key_Infrastructure_PKI_Key_Pairs|public account key]].
 The message is signed with the corresponding private account key. The response
 includes the server's public key. The server's public key will also be

spec/admin.mediawiki

@@ -11,7 +11,7 @@ That said, changes to exchange or asset variables will often entail revocation
 of all existing orders on a market, so should be done as infrequently as
 possible.
 
-'''Exchange Variables'''
+==Exchange Variables==
 
 {|
 ! variable !! relevant section !! units || default
@@ -27,14 +27,14 @@ possible.
 | broadcast timeout || [[fundamentals.mediawiki/#Exchange_Variables|Exchange Variables]] & [[community.mediawiki/#rule-1-clients-must-respond-to-all-preimage-requests|Rule 1]] || milliseconds || 60,000
 |}
 
-'''Per-asset Variables'''
+==Per-asset Variables==
 
 {|
 ! variable !! units !! description
 |-
 | lot size  || atoms ||  the minimum order quantity and the order quantity increment when an asset is the base asset
 |-
-| rate step || atoms || The minimum price rate and the price rate increment when an asset is the quote asset. [[orders.mediawiki/#Rate_Encoding|message-rate encoding]]
+| rate step || atoms || the minimum price rate and the price rate increment when an asset is the quote asset. [[orders.mediawiki/#Rate_Encoding|message-rate encoding]]
 |-
 | fee rate  || atoms/byte || the minimum fee rate for swap transactions
 |-
@@ -45,4 +45,27 @@ possible.
 
 See also [[fundamentals.mediawiki/#Exchange_Variables|Exchange Variables]].
 
-...
+==Administration API==
+
+The server will provide an HTTP API for performing various adminstrative tasks.
+
+'''API Endpoints'''
+{|
+! path      !! description
+|-
+| /config   || the current DEX configuration. See [[fundamentals.mediawiki/#Configuration_Data_Request|Configuration Data Request]]
+|-
+| /accounts || lists information about all known accounts
+|-
+| /accounts/{accountID} || list information about a specific account
+|-
+| /markets  || display status information for all markets
+|-
+| /market/{marketID} || display status information for a specific market
+|-
+| /market/{marketID}/suspend || schedule a market suspension at the end of the current epoch
+|-
+| /unban/{accountID} || clear an account's penalties and re-enable trading
+|-
+| /ban/{accountID}/{ruleNumber} || ban an account for violating [[community.mediawiki/#Rules_of_Community_Conduct|a rule]]
+|}

spec/api.mediawiki

@@ -2,4 +2,4 @@
 
 __TOC__
 
-Trade history will be made available to both websocket and HTTP clients.
+Trade history will be made available to both WebSocket and HTTP clients.

spec/comm.mediawiki

@@ -11,15 +11,15 @@ Match notification via HTTP polling or other request interval-based methods are
 thus not suitable for the DEX system.
 Persistent, full-duplex communication is critical to minimizing communication
 latencies and wasted bandwidth.
-Websockets ([https://tools.ietf.org/html/rfc6455 [4]]) are chosen as the
+WebSockets ([https://tools.ietf.org/html/rfc6455 [3]]) are chosen as the
 default and preferred communications protocol for
 the DEX exchange API.
 In addition to fulfilling the aforementioned needs, Websockets are now a
 well-established technology with client software available for integration in
 virtually all popular programming languages.
 
-Websocket messages are secured by encryption on Transport Layer
-Security (TLS) [https://tools.ietf.org/html/rfc8446 [5]] connections.
+WebSocket messages are secured by encryption on Transport Layer
+Security (TLS) [https://tools.ietf.org/html/rfc8446 [4]] connections.
 
 ==Encoding==
 
@@ -30,6 +30,9 @@ units of time are milliseconds unless otherwise specified. Location-independent
 timestamps are encoded as milliseconds since the UNIX epoch (Jan 01 00:00:00
 1970 UTC).
 
+If a timestamp must be converted to seconds, e.g. for encoding as a locktime in
+a swap contract, the timestamp should be rounded down.
+
 ===Rate Encoding===
 
 Because the rate assigned to a limit order is a quotient, the value is naturally
@@ -57,7 +60,7 @@ ID and output index (vout).
 
 In an effort to stay blockchain-protocol agnostic, the DEX accepts
 and recognizes the locating information as a single byte-array called the
-'''''coin ID''''', with the term '''''coin''''' being defined here as a some
+'''''coin ID''''', with the term '''''coin''''' being defined here as some
 amount of spendable value that is verifiable on the blockchain.
 It is up to backend and wallet developers to decide on how to properly encode the
 identifier as a coin ID. As an example, Bitcoin implements
@@ -66,7 +69,7 @@ big-endian encoded output index as the last 4 bytes.
 
 ==Message Protocol==
 
-DEX messaging is JSON-formatted [https://tools.ietf.org/html/rfc8259 [6]].
+DEX messaging is JSON-formatted [https://tools.ietf.org/html/rfc8259 [5]].
 All messages, regardless of originating party, use a common top-level
 structure called a '''Message'''.
 
@@ -145,7 +148,7 @@ The payload for a response has a structure that enables quick error checking.
 
 ==Session Authentication==
 
-Many DEX messages must be sent on an authenticated connection. Once a websocket
+Many DEX messages must be sent on an authenticated connection. Once a WebSocket
 connection is established, the client will supply their account ID and signature.
 
 '''Request route:''' <code>connect</code>, '''originator: ''' client
@@ -182,15 +185,17 @@ the client's absence. A list of any pending matches is included in the response.
 
 <code>result</code>
 {|
-! field      !! type   !! description
+! field   !! type   !! description
+|-
+| matches || &#91;object&#93; || list of [[orders.mediawiki/#Match_negotiation|Match objects]]
 |-
-| matches    || &#91;object&#93; || list of [[orders.mediawiki/#Match_negotiation|Match objects]]
+| sig     || string || hex-encoded server's signature of the serialized connection data
 |}
 
 ==HTTP==
 
 An API using HTTP for message transport may be provided for basic account
-management and server status queries, however websocket connections are to be
+management and server status queries, however webWebSocketsocket connections are to be
 the sole means for
 [[orders.mediawiki/#Client_Order_Management|placing, monitoring, and executing orders]].
 The primary reason for limiting the scope of the HTTP API is to eliminate client