decred.org/dcrdex@v1.0.3/README.md (about) 1 # <img src="docs/images/logo_wide_v2.svg" alt="DCRDEX" width="456"> 2 3 [](https://github.com/decred/dcrdex/actions) 4 [](https://blueoakcouncil.org/license/1.0.0) 5 [](https://pkg.go.dev/decred.org/dcrdex) 6 7 ## Bison Wallet and DCRDEX development 8 9 This is the repository for development of Bison Wallet, DCRDEX, and Tatanka 10 Mesh. 11 12 ## What is DCRDEX? 13 14 The [Decred Decentralized Exchange (DEX)](https://dex.decred.org/) is a system 15 that enables trustless exchange of different types of blockchain assets via a 16 familiar market-based API. DEX is a non-custodial solution for cross-chain 17 exchange based on atomic swap technology. DEX matches trading parties and 18 facilitates price discovery and the communication of swap details. 19 20 Matching is performed through a familiar exchange interface, with market and 21 limit orders and an order book. Settlement occurs on-chain. DEX's epoch-based 22 matching algorithm and rules of community conduct ensure that the order book 23 action you see is real and not an army of bots. 24 25 Trades are performed directly between users through on-chain contracts with no 26 actual reliance on DEX, though swap details must be reported both as a 27 courtesy and to prove compliance with trading rules. Trades are settled with 28 pure 4-transaction atomic swaps and nothing else. Because DEX collects no 29 trading fees, there's no intermediary token and no fee transactions. 30 31 Although trading fees are not collected, DEX does require a one-time 32 registration fee to be paid on-chain. Atomic swap technology secures all trades, 33 but client software must still adhere to a set of policies to ensure orderly 34 settlement of matches. The maximum penalty imposable by DEX is loss of trading 35 privileges and forfeiture of registration fee. 36 37 ## What is Bison Wallet 38 39 Bison Wallet is a multi-wallet developed in concert with DCRDEX and Tatanka 40 Mesh. Bison Wallet leverages state-of-the-art blockchain technology to bring 41 more features and more privacy for your favorite assets. DCRDEX is built-in, as 42 well as advanced trading features like market-making and arbitrage, directly 43 from your wallet. 44 45 Our goal is to find a balance of convenience and privacy that works for you, 46 while giving you access to advanced features most wallets ignore. For many 47 assets, we can cut out the middleman altogether and allow you to interact 48 directly with the blockchain network. This type of wallet is highly-resilient to 49 data collection and censorship. 50 51 We also focus on bringing advanced, asset-specific features for out wallets. 52 With Decred, you can use StakeShuffle to further anonymize your funds, or stake 53 your DCR and earn some block rewards. The Zcash wallet exposes unified addresses 54 and shielded pools, and operates on a shielded-first principle that makes 55 privacy effortless. Keep an eye on development here. We are dedicated to 56 exposing these technologies to the communities that want them. 57 58 ## What is Tatanka Mesh 59 60 Tatanka Mesh (Tatanka, the mesh) is the evolution of DCRDEX. Where DCRDEX relies 61 on a central server for maintaining order books and policing trades, Tatanka is 62 a decentralized P2P protocol that enables a network of subscribers to 63 collectively perform these tasks. Here are the three critical services that 64 Tatanka Mesh provides. 65 66 - Enhance the ability for users to connect and to share data both publicly and privately 67 - Aggregate reputation data and monitor fidelity bonds. Tatanka can limit 68 access to users who earn a bad reputation 69 - Oracle services for fiat exchange rates and blockchain transaction fee rates 70 71 The mesh collects no fees for its services. Trades are performed using trustless 72 atomic swaps that exchange funds directly between wallets. 73 74 Going P2P empowers our users to trade directly, enhancing security, 75 censorship-resistance, privacy. and self-sovereignty. 76 77 ## Contents 78 79 - [Getting Started](#getting-started) 80 - [Important Stuff to Know](#important-stuff-to-know) 81 - [Fees](#fees) 82 - [DEX Specification](#dex-specification) 83 - [Contribute](#contribute) 84 - [Source](#source) 85 86 ## Getting Started 87 88 To trade on DCRDEX, you can use Bison Wallet. There are a few simple options 89 for obtaining Bison Wallet. The standalone wallet is strongly recommended as 90 it is the easiest to setup and generally has the most up-to-date downloads. Pick 91 **just one** method: 92 93 1. From version 1.0, installers are available for all major operating systems 94 2. Download standalone Bison Wallet for your operating system for the 95 [latest release on GitHub](https://github.com/decred/dcrdex/releases). 96 3. Use your operating system's package manager. See [OS Packages](#os-packages) 97 for more info. 98 4. [Use Decrediton](https://docs.decred.org/wallets/decrediton/decrediton-setup/), 99 the official graphical Decred wallet, which integrates Bison Wallet, and go 100 to the DEX tab. 101 5. Build the standalone client [from source](https://github.com/decred/dcrdex/wiki/Client-Installation-and-Configuration#advanced-client-installation). 102 103 See the [Client Installation and Configuration](https://github.com/decred/dcrdex/wiki/Client-Installation-and-Configuration) 104 page on the wiki for more information and a detailed walk-through of the initial setup. 105 106 Almost everyone will just want the client to trade on existing markets, but if 107 you want to set up a new DEX server and host markets of your choice, see 108 [Server Installation](https://github.com/decred/dcrdex/wiki/Server-Installation). 109 110 ## OS Packages 111 112 We are in the process of adding the application to various OS package managers: 113 114 - Arch Linux ([AUR](https://aur.archlinux.org/packages/dcrdex)). e.g. `$ yay dcrdex`. Accessible to [Arch-based distros](https://wiki.archlinux.org/title/Arch-based_distributions) like Manjaro. 115 - MacOS. Homebrew cask **coming soon**. 116 - Windows. `winget` package **coming soon**. 117 - Debian/Fedora. apt repository **coming soon**. 118 119 ## Important Stuff to Know 120 121 Trades settle on-chain and require block confirmations. Trades do not settle instantly. 122 In some cases, they may take hours to settle. 123 **The client software should not be shut down until you are absolutely certain that your trades have settled**. 124 125 **The client has to stay connected for the full duration of trade settlement**. 126 Losses of connectivity of a couple minutes are fine, but don't push it. 127 A loss of internet connectivity for more than 20 hours during trade settlement has the potential to result in lost funds. 128 Simply losing your connection to the DEX server does not put funds at risk. 129 You would have to lose connection to an entire blockchain network. 130 131 **There are initially limits on the amount of ordering you can do**. 132 We'll get these limits displayed somewhere soon, but in the meantime, 133 start with some smaller orders to build up your reputation. As you complete 134 orders, your limit will go up. 135 136 **If you fail to complete swaps** when your orders are matched, your account 137 will accumulate strikes that may lead to your account becoming automatically 138 suspended. These situations are not always intentional (e.g. prolonged loss of 139 internet access, crashed computer, etc.), so for technical assistance, please 140 reach out 141 [on Matrix](https://matrix.to/#/!mlRZqBtfWHrcmgdTWB:decred.org?via=decred.org&via=matrix.org). 142 143 ## Fees 144 145 DEX does not collect any fees on the trades, but since all swap transactions 146 occur on-chain and are created directly by the users, they will pay network 147 transaction fees. Transaction fees vary based on how orders are matched. Fee 148 estimates are shown during order creation, and the realized fees are displayed 149 on the order details page. 150 151 To ensure that on-chain transaction fees do not eat a significant portion of the 152 order quantity, orders must be specified in increments of a minimum lot size. 153 To illustrate, if on-chain transaction fees worked out to $5, and a user was able 154 to place an order to trade $10, they would lose half of their trade to 155 transaction fees. For chains with single-match fees of $5, if the operator wanted 156 to limit possible fees to under 1% of the trade, the minimum lot size would need 157 to be set to about $500. 158 159 The scenario with the lowest fees is for an entire order to be consumed by a 160 single match. If this happens, the user pays the fees for two transactions: one 161 on the chain of the asset the user is selling and one on the chain of the asset 162 the user is buying. The worst case is for the order to be filled in multiple 163 matches each of one lot in amount, potentially requiring as many swaps as lots 164 in the order. 165 Check the 166 [dex specification](https://github.com/decred/dcrdex/blob/master/spec/atomic.mediawiki) 167 for more details about how atomic swaps work. 168 169 ## DEX Specification 170 171 The [DEX specification](spec/README.mediawiki) details the messaging and trading 172 protocols required to use the Market API. Not only is the code in 173 the **decred/dcrdex** repository open-source, but the entire protocol is 174 open-source. So anyone can, in principle, write their own client or server based 175 on the specification. Such an endeavor would be ill-advised in these early 176 stages, while the protocols are undergoing constant change. 177 178 ## Contribute 179 180 **Looking to contribute? We need your help** to make DEX #1. 181 182 Nearly all development is done in Go and JavaScript. Work is coordinated 183 through [the repo issues](https://github.com/decred/dcrdex/issues), 184 so that's the best place to start. 185 Before beginning work, chat with us in the 186 [DEX Development room](https://matrix.to/#/!EzTSRQITaqHuFBDFhM:decred.org?via=decred.org&via=matrix.org&via=zettaport.com). 187 The pace of development is pretty fast right now, so you'll be expected to keep 188 your pull requests moving through the review process. 189 190 Check out these wiki pages for more information. 191 192 - [Getting Started Contributing](../../wiki/Contribution-Guide) 193 - [Backend Development](../../wiki/Backend-Development) 194 - [Run **dcrdex** and **bisonw** on simnet](../../wiki/Simnet-Testing). Recommended for development. 195 - [Run **bisonw** on testnet](../../wiki/Testnet-Testing). Recommended for poking around. 196 - [Run the test app server](../../wiki/Test-App-Server). Useful for GUI development, or just to try everything out without needing to create wallets or connect to a **dcrdex** server. 197 198 ## Source 199 200 The DEX [specification](spec/README.mediawiki) was drafted following stakeholder 201 approval of the 202 [specification proposal](https://proposals.decred.org/proposals/a4f2a91c8589b2e5a955798d6c0f4f77f2eec13b62063c5f4102c21913dcaf32). 203 204 The source code for the DEX server and client are being developed according to 205 the specification. This undertaking was approved via a second DEX 206 [development proposal](https://proposals.decred.org/proposals/417607aaedff2942ff3701cdb4eff76637eca4ed7f7ba816e5c0bd2e971602e1). 207 208 ## FAQS 209 210 - How can I integrate new assets? To add new assets, follow the instructions [here](https://github.com/decred/dcrdex/blob/master/spec/fundamentals.mediawiki/#adding-new-assets) and see existing implementations [here](https://github.com/decred/dcrdex/tree/master/server/asset).