fix links and typos. admin API. trade resumption

dex/msgjson/types.go

@@ -370,7 +370,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"`
@@ -661,7 +661,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,7 +1,4 @@
-=Decred DEX=
-
-This is the repository for the Decred Distributed Exchange (DEX), for which this
-document provides the '''DRAFT''' specification.
+=Decred DEX Specification=
 
 __TOC__
 
@@ -11,13 +8,13 @@ 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.
 
-The vast majority of cryptocurrency trading is currently 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.
-The moment you send your coin to a third-party exchange, those benefits all go
-out the window.
+Currently, the majority of cryptocurrency trading is performed via centralized,
+custodial exchanges.
+These exchanges have fill 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.
 
 Several projects have attempted to address this misalignment by
 replacing the exchange with a blockchain or a token, and they have met with
@@ -42,10 +39,14 @@ censorship difficult.
 While trades are fully trustless, steps are taken to discourage malicious
 clients from hindering normal trade activity.
 All clients pay a non-refundable registration fee.
-Registered clients are bound by the
+Registered clients are then bound to the
 [[community.mediawiki|rules of community conduct]], violation of which typically
 results in loss of trading privileges up to and including a permanent ban.
 
+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.
+
 ==Contents==
 
 The remaining content details the Decred DEX protocol.
@@ -71,15 +72,16 @@ describes the notable design aspects that facilitate an exchange service with
 the features described above.
 
 * [[fundamentals.mediawiki/#Exchange_Variables|Exchange Variables]]
-** [[comm.mediawiki/#Global_Variables|Global Variables]]
-** [[comm.mediawiki/#Asset_Variables|Asset Variables]]
-** [[comm.mediawiki/#Market_Variables|Market Variables]]
-** [[comm.mediawiki/#Configuration_Data_Request|Configuration Data Request]]
+** [[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]]
-** [[comm.mediawiki/#Epoch_Time|Epoch Time]]
-** [[comm.mediawiki/#Pseudorandom_Order_Matching|Pseudorandom 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.

spec/admin.mediawiki

@@ -34,7 +34,7 @@ possible.
 |-
 | 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,25 @@ 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
+|}

spec/comm.mediawiki

@@ -57,7 +57,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

spec/fundamentals.mediawiki

@@ -104,7 +104,7 @@ respond with its current configuration.
 |-
 | btimeout       || int   || the broadcast timeout
 |-
-| regfee         || int   || registration fee (Decred atoms)
+| fee            || int   || registration fee (Decred atoms)
 |-
 | regfeeconfirms || int   || required confirmations for the registration fee payment transaction
 |-
@@ -138,19 +138,23 @@ respond with its current configuration.
 '''Market object'''
 
 {|
-! field      !! type   !! description
+! field       !! type   !! description
 |-
-| name       || string || market name
+| name        || string || market name
 |-
-| base       || int    || base asset ID
+| base        || int    || base asset ID
 |-
-| quote      || int    || quote asset ID
+| quote       || int    || quote asset ID
 |-
-| epochlen   || int    || the [[#Epochbased_Order_Matching|epoch duration]] (milliseconds)
+| epochlen    || int    || the [[#Epochbased_Order_Matching|epoch duration]] (milliseconds)
 |-
-| startepoch || int    || the epoch number at which trading did or will commence. May be in the future e.g. [[orders.mediawiki/#Trade_Suspension|after maintenance]]
+| buybuffer   || float  || the [[orders.mediawiki/#Market_Buy_Orders|market buy buffer]]
 |-
-| buybuffer  || float  || the [[orders.mediawiki/#Market_Buy_Orders|market buy buffer]]
+| startepoch  || int    || the epoch number at which trading did or will commence. May be in the future e.g. [[orders.mediawiki/#Trade_Suspension|after maintenance]]
+|-
+| finalepoch  || int    || the epoch number at which trading will be suspended. Only present when a suspension is scheduled
+|-
+| persistbook || bool   || whether or not booked orders will be persisted through a scheduled suspension. Only present when a suspension is scheduled
 |}
 
 ==Fees==
@@ -314,17 +318,20 @@ broadcast transactions to each of the blockchain networks involved in
 assets supported.
 While operation via a surrogate blockchain data service such as a block explorer
 is potentially feasible, it would entail significant security risks.
-Initial development will require a direct connection to full nodes of each
-asset's blockchain.
-
-Adding support for an asset is accomplished by implementing a particular
-[https://golang.org/ Go] interface.
-The interface is exported and compiled with <code>-buildmode=plugin</code> to enable
-dynamic importing by the exchange operator.
-The operator will decide which plugins to import via configuration file.
-As the interface is expected to evolve greatly during initial implementation,
-the specifics of the interface structure will be released at a later time.
-
-With the exception of Decred and Bitcoin, which will be implemented during
+Initial development will require that the server have a direct connection to
+full nodes of each asset's blockchain.
+
+==Adding New Assets==
+
+Adding support for an asset is accomplished by writing a
+[https://golang.org/ Go] package with types that implement a particular set of
+interfaces, defined [https://github.com/decred/dcrdex/blob/master/server/asset/common.go here]
+and [https://github.com/decred/dcrdex/blob/master/server/asset/driver.go here].
+There are then two ways to import the asset backend into the server software.
+
+# The package is compiled with <code>-buildmode=plugin</code> and imported at runtime by specifying the plugin in the server configuration.
+# The backend is added to the dcrdex repository, and imported directly at compile time.
+
+With the exception of a small handful of assets which will be implemented during
 initial phases of DEX development, it is expected that development communities
 will release their own appropriately vetted plugins.

spec/orders.mediawiki

@@ -316,7 +316,7 @@ All order serializations have common '''prefix''' fields.
 |-
 | tserver    || 8  || int || the server's UNIX timestamp (milliseconds). zero for client signature
 |-
-| commitment || 32 || string || hex-encoded cryptographic commitment
+| com || 32 || string || hex-encoded cryptographic commitment
 |}
 
 ===Order ID===
@@ -530,7 +530,7 @@ This is by design and discourages certain types of spoofing.
 |-
 | colspan="3" align="center" | 9 prefix fields
 |-
-| orderid   || string || hex-encoded order ID
+| targetid  || string || hex-encoded order ID
 |-
 | sig       || string || client hex-encoded signature of the serialized order data. serialization described below
 |}
@@ -547,11 +547,11 @@ This is by design and discourages certain types of spoofing.
 
 <code>result</code>
 {|
-! field     !! type   !! description
+! field   !! type   !! description
 |-
-| sig       || string || server hex-encoded signature of the serialize order data, after adding the DEX timestamp
+| sig     || string || server hex-encoded signature of the serialize order data, after adding the DEX timestamp
 |-
-| server time || int  || the server's UNIX timestamp (milliseconds)
+| tserver || int    || the server's UNIX timestamp (milliseconds)
 |}
 
 ==Preimage Reveal==
@@ -623,14 +623,18 @@ transaction and inform the server with an <code>init</code> notification
 |-
 | matchid   || string    || the match ID to use for progress notifications
 |-
-| quantity  || int    || the matched amount, in atoms of the base asset
+| qty       || int    || the matched amount, in atoms of the base asset
 |-
 | rate      || int    || the matched price rate. [[comm.mediawiki/#Rate_Encoding|message-rate encoding]]
 |-
-| tserver || int    || server's UNIX timestamp (milliseconds)
+| tserver   || int    || server's UNIX timestamp (milliseconds)
 |-
 | address   || string || the counterparty's receiving address
 |-
+| side      || int    || the client's side in the match. 0 = maker, 1 = taker
+|-
+| status    || int    || only provided in 'connect' response. See [[https://github.com/decred/dcrdex/blob/master/dex/order/match.go|match.go]] for codes.
+|-
 | sig       || string || DEX's hex-encoded signature of the serialized notification data. serialization described below
 |}
 
@@ -674,8 +678,6 @@ relay to the matching party.
 |-
 | coinid    || string || hex-encoded coin ID
 |-
-| timestamp  || int    || client's UNIX timestamp (milliseconds)
-|-
 | contract   || string || hex-encoded swap redeem script
 |-
 | sig        || string || client signature of the serialized notification. serialization described below
@@ -690,9 +692,7 @@ relay to the matching party.
 |-
 | matchid    || 32  || the ID assigned to this match
 |-
-| coin ID    || asset-dependent  || the coin ID
-|-
-| timestamp  || 8  || the client's UNIX timestamp (milliseconds)
+| coinid     || asset-dependent  || the coin ID
 |-
 | contract   || asset-dependent || swap redeem script
 |}
@@ -759,12 +759,10 @@ When a client has redeemed their contract, they will notify the server.
 |-
 | secret     || string || the hex-encoded swap contract secret
 |-
-| timestamp  || int    || client's UNIX timestamp (milliseconds)
-|-
 | sig        || string || client signature of the serialized notification. serialization described below
 |}
 
-<code>result</code>
+'''Redeem serialization'''
 {|
 ! field      !! size (bytes)  !! description
 |-
@@ -888,7 +886,21 @@ does not reconnect before the next [[comm.mediawiki/#Session_Authentication|star
 |-
 | finalepoch  || uint64 || the last epoch during which orders will be collected and matched
 |-
-| suspendtime || uint64 || the UNIX timestamp corresponding to the end of the final epoch (milliseconds).
+| suspendtime || uint64 || the UNIX timestamp corresponding to the end of the final epoch (milliseconds)
 |-
 | persistbook || bool   || whether standing limit orders will persist through the suspension
 |}
+
+Clients will also be informed when trading is resumed.
+
+'''Request route: ''' <code>resumption</code>, '''originator:''' DEX
+<code>payload</code>
+{|
+! field       !! type   !! description
+|-
+| marketid    || string || the market ID
+|-
+| startepoch  || uint64 || the epoch number at which trading did or will commence. May be in the future
+|-
+| epochlen || uint64 || the [[#Epochbased_Order_Matching|epoch duration]] (milliseconds)
+|}