decred.org/dcrdex@v1.0.5/spec/atomic.mediawiki (about) 1 =Atomic Settlement= 2 3 __TOC__ 4 5 In order to facilitate trustless, non-custodial exchange, the DEX leverages an 6 atomic swap process that enables all parties to maintain full control over their 7 assets at every step. 8 The DEX primarily acts as a matchmaker, connecting two orders and relaying 9 messages between the two clients. 10 Additionally, the DEX performs some trade monitoring to ensure that parties are 11 acting in good faith. 12 Clients who fail to act on their trades appropriately will be issued a penalty 13 in accordance with the [[community.mediawiki/#community-conduct|rules of community conduct]]. 14 15 The following cases are meant to provide a high-level overview of the trade 16 process, and to illustrate how to handle a perfect match, a partial fill, and 17 multiple matches within an epoch. For the sake of illustration, the following 18 simplifications are made. 19 20 <img src="images/ab-profiles.png" align="right"> 21 # The lot size for the market is 1 DCR. 22 # All backing funds for the orders are in the form of a single coin. 23 # There are no fees. 24 25 The examples involve a participant named Alice, who holds some DCR and would 26 like to exchange it for some BTC. 27 The market is a DCR/BTC market, where DCR is the “base asset” and BTC is the 28 “quote asset”. 29 Order quantities are in units of DCR, and the rate offered in a limit order is 30 denominated in BTC. 31 32 ==Case A: Perfect match== 33 34 In the most basic case, Alice and a trader named Bob are the only participants 35 and their orders match perfectly. 36 37 <img src="images/alice-order.png" align="left"> 38 '''A1: Alice places a limit order''' to sell 3 DCR at 0.1 BTC per DCR for a 39 total of 0.3 BTC. 40 As a limit order, Alice must specify both the quantity and the price, as a rate, 41 as well as her BTC address. 42 Alice signs the order information. The signature provides proof of the 43 order and justifies any penalties imposed on Alice should she fail to follow 44 through on a trade. 45 46 <img src="images/bob-order.png" align="right"> 47 '''A2''': During some later epoch, '''Bob places a market order''' to buy DCR 48 with BTC at the best available price. 49 Bob’s order will contain both an address and a signature. 50 As a market order, Bob’s order must match in this epoch. Any unfilled portion 51 is immediately canceled. 52 53 '''A3''': At the end of the epoch, the '''DEX performs a match cycle''', 54 recognizes the match, and informs both Alice and Bob that a match has occurred. 55 Because the order quantities are identical, the orders are simply removed from 56 the book and set aside for monitoring. 57 The DEX informs both clients that a match has been made and provides Bob with 58 Alice’s address. 59 60 <img src="images/ab-match.png"> 61 62 '''A4''': Because Alice is the maker, she will broadcast her initialization 63 transaction first. 64 She will be expected to broadcast and report her transaction to the DEX 65 within a specified amount of time. 66 67 Before Alice can '''prepare her initialization transaction''', she must generate 68 a key known only to herself. 69 From the key, Alice generates a “lock” and constructs a swap contract 70 such that if someone can provide both Alice’s key and the pubkey for Bob’s 71 specified address, they can spend the output. 72 In practice, the key is simply a random 32-byte sequence, and the lock is its 73 hash. 74 75 In addition, Alice constructs the contract with a second, alternative lock 76 that allows her to spend the output herself, but only if the output remains 77 unspent for a specified amount of time. Alice sets her timelock to 20 hours. 78 79 '''Alice broadcasts her initialization transaction''' to the Decred network. 80 She informs the DEX of the transaction details and sends the lock, which the 81 DEX relays to Bob. Alice '''does not''' reveal the key that she created. 82 83 <img src="images/alice-init.png"> 84 85 '''A5: Bob inspects Alice's transaction. 86 After the requisite number of confirmations, Bob prepares his initialization 87 transaction'''. He uses Alice's lock here as well, and creates a swap contract 88 satisfied by Alice’s key and the pubkey for Alice’s address. 89 90 Bob sets his timelock to 8 hours. 91 Bob should also check that the timelock in Alice's initialization is set to 20 92 hours. 93 If Alice’s timelock duration is set near or below Bob’s timelock duration, Alice 94 could potentially spend the DCR output before Bob. 95 96 '''Bob broadcasts his initialization transaction''' to the Bitcoin network. 97 He informs the DEX of the transaction details, and the DEX relays the 98 information to Alice. 99 100 <img src="images/bob-init.png"> 101 102 '''A6: Alice prepares a redemption transaction''' that spends the output from 103 Bob’s initialization transaction to her own address. 104 In order to spend the Bitcoin from Bob’s transaction, she needs to provide the 105 key created in step 4. 106 107 '''Alice broadcasts her redemption transaction''' to the Bitcoin network. 108 Though both the DEX and Bob are capable of monitoring for the transaction, it 109 is expected that Alice informs the DEX server of the transaction details anyway. 110 The DEX server will notify Bob of the details. 111 112 <img src="images/alice-redeem.png"> 113 114 '''A7: Bob prepares his redemption transaction''' using the key gleaned from 115 Alice’s redemption transaction and the output from Alice’s initialization 116 transaction. 117 118 '''Bob broadcasts his redemption transaction to the Decred network, completing 119 the atomic swap.''' 120 121 <img src="images/bob-redeem.png"> 122 123 ==Case B: Multi-taker with partial fill== 124 125 In case B, Alice is similarly trying to sell 3 DCR for 0.3 BTC, but the match 126 found by the DEX is not perfect this time. 127 128 '''B1''': Same as A1. Alice submits her signed order to the DEX. 129 130 '''B2''': Bob places a market order for 0.1 BTC worth of DCR at market price. 131 A new client, Carl, places an identical market order for 0.1 BTC worth of DCR. 132 133 <img src="images/abc-order.png"> 134 135 '''B3''': The DEX finds the match and informs all parties, providing Alice with 136 Bob and Carl's addresses. 137 The DEX cannot simply remove Alice’s order, because it is only partially filled. 138 In this case, the DEX does not remove the order from the order book, instead 139 just marking it partially filled and calculating the remaining quantity. The 140 order is returned to the order book and is immediately able to match again. 141 142 <img src="images/abc-match.png"> 143 144 <img src="images/a-init-bc.png" align="right"> 145 '''B4''': As the maker, Alice goes first again. 146 She groups her matches from the epoch and creates two different keys, one for 147 Bob and one for Carl. She sets her timelocks to 20 hours. 148 '''Alice broadcasts her initialization transaction''' to the Decred network and 149 informs the DEX about the transaction details, which the DEX relays to Bob and 150 Carl. 151 152 <img src="images/bc-init.png" align="right"> 153 '''B5''' After waiting the requisite number of confirmations, Bob and Carl 154 prepare their initialization transactions using the locks from Alice's 155 transaction. They broadcast their transactions. 156 157 '''B6 and B7''' follow naturally from case A, with Alice creating two redemption 158 transactions, one for Bob and one for Carl. 159 Bob and Carl then follow up with their own redemptions.