From f482b891e6dd3f81e2824e4496586632319fdd02 Mon Sep 17 00:00:00 2001 From: buck54321 Date: Tue, 16 Jun 2020 10:15:22 -0500 Subject: [PATCH] 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 | 4 +- spec/README.mediawiki | 142 ++++++++++++++++++------------------ spec/accounts.mediawiki | 2 +- spec/admin.mediawiki | 31 +++++++- spec/api.mediawiki | 2 +- spec/comm.mediawiki | 23 +++--- spec/fundamentals.mediawiki | 49 +++++++------ spec/orders.mediawiki | 76 +++++++++++-------- spec/references.mediawiki | 12 ++- 9 files changed, 197 insertions(+), 144 deletions(-) diff --git a/dex/msgjson/types.go b/dex/msgjson/types.go index 133b4620b7..98f834b13f 100644 --- a/dex/msgjson/types.go +++ b/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"` diff --git a/spec/README.mediawiki b/spec/README.mediawiki index e1e7ecc834..fc0647c7f6 100644 --- a/spec/README.mediawiki +++ b/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. diff --git a/spec/accounts.mediawiki b/spec/accounts.mediawiki index 51c5cef076..b7de25e8e0 100644 --- a/spec/accounts.mediawiki +++ b/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 diff --git a/spec/admin.mediawiki b/spec/admin.mediawiki index e332dc61d4..e528ef7110 100644 --- a/spec/admin.mediawiki +++ b/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]] +|} \ No newline at end of file diff --git a/spec/api.mediawiki b/spec/api.mediawiki index 0819346237..7ef32d5cf9 100644 --- a/spec/api.mediawiki +++ b/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. diff --git a/spec/comm.mediawiki b/spec/comm.mediawiki index d73f1ad07a..181c207da0 100644 --- a/spec/comm.mediawiki +++ b/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:''' connect, '''originator: ''' client @@ -182,15 +185,17 @@ the client's absence. A list of any pending matches is included in the response. result {| -! field !! type !! description +! field !! type !! description +|- +| matches || [object] || list of [[orders.mediawiki/#Match_negotiation|Match objects]] |- -| matches || [object] || 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 diff --git a/spec/fundamentals.mediawiki b/spec/fundamentals.mediawiki index 97a3ba2da4..2c81c3afe9 100644 --- a/spec/fundamentals.mediawiki +++ b/spec/fundamentals.mediawiki @@ -53,7 +53,7 @@ In particular, for ''lot size'' '''''l''''', the requested ''order quantity'', Every asset is assigned a unique integer ID that will be used to identify the asset in serialized structures. Whenever possible, the ID is the same as the BIP-0044 registered coin type index -[https://github.com/satoshilabs/slips/blob/master/slip-0044.md [7]]. +[https://github.com/satoshilabs/slips/blob/master/slip-0044.md [6]]. When the asset is the quote asset, a '''price increment''' is enforced. The '''rate''', '''''r''''', of a limit order must be an integer multiple of the @@ -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 -buildmode=plugin 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 -buildmode=plugin 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. diff --git a/spec/orders.mediawiki b/spec/orders.mediawiki index 4bc282215a..93c3f2ea71 100644 --- a/spec/orders.mediawiki +++ b/spec/orders.mediawiki @@ -59,7 +59,7 @@ re-subscribe to the market to synchronize the order book from scratch. {| ! field !! type !! description |- -| marketid || string || An identifier used to identify this market in notifications +| marketid || string || A unique market identifier, the market ID. |- | seq || int || A sequence ID |- @@ -75,7 +75,7 @@ re-subscribe to the market to synchronize the order book from scratch. |- | seq || int || A sequence ID || superceded in orderbook response |- -| marketid || string || A unique market identifier || +| marketid || string || the market ID || |- | oid || string || the order ID || |- @@ -156,7 +156,7 @@ independently verify matching. |} A client can '''unsubscribe''' from order book updates without closing the -websocket connection. +WebSocket connection. '''Request route:''' unsub_orderbook, '''originator: ''' client @@ -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. result {| -! 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== @@ -591,7 +591,7 @@ the checksum generated from their local copy of the epoch queue. ==Match negotiation== Swap negotiation details will be relayed through the DEX with a series of -notifications or progress reports. +notifications. Both the DEX and the clients will need to serialize and sign the notification data. The originator includes their signature with the request, while the recipient will return an '''acknowledgement''', or a list of @@ -623,14 +623,18 @@ transaction and inform the server with an init 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]] |- -| timestamp || 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. For 'match' requests, status is 0 = 'MakerSwapCast'. 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 |} @@ -647,11 +651,15 @@ transaction and inform the server with an init notification |- | rate || 8 || the matched price rate. [[comm.mediawiki/#Rate_Encoding|message-rate encoding]] |- -| timestamp || 8 || server's UNIX timestamp (milliseconds) +| tserver || 8 || server's UNIX timestamp (milliseconds) |- | address || varies || UTF-8 encoded receiving address for the match |} +'''The tserver value is used as the basis for the the locktimes.''' +If it is necessary to convert the time to seconds, the value should be rounded +down. + The client will respond with a list of signed match acknowledgements. After a client broadcasts their initialization transaction, they are @@ -670,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 @@ -686,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 |} @@ -755,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 |} -result +'''Redeem serialization''' {| ! field !! size (bytes) !! description |- @@ -817,7 +819,7 @@ The client will respond with an acknowledgement. The taker will get the key from the maker's redemption and broadcast their own redemption transaction. -==Match revocation== +==Match Revocation== A match can be revoked by the server if a client fails to act within the [[fundamentals.mediawiki/#Exchange_Variables|broadcast timeout]]. A match revocation will result in @@ -858,11 +860,9 @@ During trade suspension, standing limit orders are not necessarily revoked. If the server intentionally suspends operations, they should provide a notification to connected clients as early as possible, ideally with several epochs for the client to get their orders situated before matching ceases. -The epoch specified in the suspension notification is the first epoch for which -orders will no longer be accepted. Users should expect to lose connection -during suspension. When possible, the server should settle all existing matches -before closing connections. If that is not possible, clients will need to -reconnect and complete settlement when the server comes back online. + +Clients should be prepared to lose connection during suspension. Clients will +need to reconnect and complete settlement when the server comes back online. If the server disconnects without notice, it is expected that orders placed during the current epoch are revoked at no penalty to the client and that @@ -880,9 +880,27 @@ does not reconnect before the next [[comm.mediawiki/#Session_Authentication|star payload {| -! field !! type !! description +! field !! type !! description +|- +| marketid || string || the market ID +|- +| 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) +|- +| persistbook || bool || whether standing limit orders will persist through the suspension +|} + +Clients will also be informed when trading is resumed. + +'''Request route: ''' resumption, '''originator:''' DEX +payload +{| +! field !! type !! description +|- +| marketid || string || the market ID |- -| epoch || int || the epoch in which the suspension will start +| startepoch || uint64 || the epoch number at which trading did or will commence. May be in the future |- -| persist || bool || whether standing limit orders will persist through the suspension +| epochlen || uint64 || the [[#Epochbased_Order_Matching|epoch duration]] (milliseconds) |} diff --git a/spec/references.mediawiki b/spec/references.mediawiki index 02764b5861..8fd734c362 100644 --- a/spec/references.mediawiki +++ b/spec/references.mediawiki @@ -2,14 +2,12 @@ [1] Teall, John L., Financial Trading and Investing, p. 336 (2013) -[2] [https://www.sec.gov/comments/sr-nysearca-2019-01/srnysearca201901-5164833-183434.pdf Bitwise Presentation to the U.S. Securities and Exchange Commission] (2019) +[2] [https://github.com/decred/atomicswap Atomic Swaps] -[3] [https://github.com/decred/atomicswap Atomic Swaps] +[3] [https://tools.ietf.org/html/rfc6455 The WebSocket Protocol] -[4] [https://tools.ietf.org/html/rfc6455 The WebSocket Protocol] +[4] [https://tools.ietf.org/html/rfc8446 Transport Layer Security 1.3] -[5] [https://tools.ietf.org/html/rfc8446 Transport Layer Security 1.3] +[5] [https://tools.ietf.org/html/rfc8259 JSON] -[6] [https://tools.ietf.org/html/rfc8259 JSON] - -[7] [https://github.com/satoshilabs/slips/blob/master/slip-0044.md BIP-0044 Registered Coins] +[6] [https://github.com/satoshilabs/slips/blob/master/slip-0044.md BIP-0044 Registered Coins]