├── .editorconfig ├── .gitignore ├── CONTRIBUTING.adoc ├── README.md ├── archive.adoc ├── backup-recovery.adoc ├── bisq-mobile.adoc ├── btcnode.adoc ├── build.gradle ├── compensation.adoc ├── contributor-checklist.adoc ├── css └── bisq.css ├── dao-technical-overview.adoc ├── dao-user-reference.adoc ├── dao.adoc ├── dao ├── overview.adoc ├── phase-zero.adoc ├── phase-zero │ ├── README.adoc │ ├── bsq-creation-destruction.png │ ├── bsq-distribution.png │ ├── bsq-uses.png │ ├── limitations.png │ └── volume.png └── specification.adoc ├── docinfo-footer.html ├── exchange ├── howto │ ├── add-alternative-base-currency.adoc │ ├── collectd.conf │ ├── images │ │ ├── asset-hierarchy.png │ │ └── asset-listing-fee.png │ ├── manual-dispute-payout.adoc │ ├── run-price-relay-node.adoc │ └── run-seednode.adoc ├── images │ ├── payment-protocol.png │ ├── trade-process-detail.png │ └── trade-process-overview.png └── whitepaper.adoc ├── getting-started-dao-traders.adoc ├── getting-started-dao.adoc ├── getting-started.adoc ├── gradle └── wrapper │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── gradlew ├── gradlew.bat ├── images ├── account-signing-details-pop.png ├── account-signing-limit-details.png ├── add-new-bsq-account.png ├── after-adding-fiat-account.png ├── altcoins-instant.png ├── before-adding-fiat-account.png ├── bisq-dao-data-model.png ├── bisq-docs.png ├── bsq-block-explorer-trading.png ├── bsq-block-explorer-voting.png ├── bsq-buy-offers.png ├── bsq-wallet-address.png ├── buyer-seller-address.png ├── check-dao-timing.png ├── closing-message.png ├── complete-trade.png ├── configure-fiat-account.png ├── configure-offer-alert.png ├── configure-price-alert.png ├── confirm-deal.png ├── dao-vote-results.png ├── dao-voting.png ├── deposit-details.png ├── determine-winner.png ├── engage-arbitrator-v116.png ├── external-link-ltr-icon-grey.svg ├── favicon.ico ├── fund-bisq-wallet.png ├── get-bsq-address-094.png ├── get-pubkey-hex.png ├── include-private-keys.png ├── make-compensation-request.png ├── make-dao-proposal.png ├── mark-payment-sent.png ├── market-screen.png ├── mobile-notifications-architecture.png ├── mobile-notifications-setup.png ├── multisig-payout-tool.png ├── p2sh-multisig-output-script.png ├── password-active.png ├── password-removed.png ├── peer-can-sign-offer-listing.png ├── quick-link-1.png ├── quick-link-2.png ├── quick-link-3.png ├── quick-link-4.png ├── remaining-time-to-pay.png ├── repeat-trading-peer.png ├── seed-words.png ├── select-an-offer.png ├── seller-payment-details.png ├── set-password.png ├── start-mediation.png ├── start-trader-chat.png ├── trading-fee-toggle-focused.png ├── trading-fee-toggle.png ├── user-dao-diagram.png ├── vote-proposal.png ├── vote-reveal-popup.png ├── vote-submit.png ├── voting-cycle-overview.png └── wallet-data.png ├── index.adoc ├── intro.adoc ├── manual-dispute-payout.adoc ├── payment-account-age-witness.adoc ├── payment-methods.adoc ├── proposals.adoc ├── roles.adoc ├── secure-wallet.adoc ├── trading-rules.adoc └── user-dao-intro.adoc /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | indent_style = space 5 | indent_size = 4 6 | continuation_indent_size = 8 7 | end_of_line = lf 8 | charset = utf-8 9 | trim_trailing_whitespace = true 10 | insert_final_newline = true 11 | 12 | [.idea/codeStyles/*.xml] 13 | indent_size = 2 14 | insert_final_newline = false 15 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Gradle 2 | .gradle 3 | build 4 | 5 | # IDEA 6 | .idea 7 | *.iml 8 | 9 | # macOS 10 | .DS_Store 11 | 12 | # Vim 13 | *.sw[op] 14 | -------------------------------------------------------------------------------- /CONTRIBUTING.adoc: -------------------------------------------------------------------------------- 1 | = Contributing to bisq-network Git repositories 2 | 3 | This document contains general contributor guidelines that apply to all bisq-network Git repositories. 4 | 5 | == Configure Git user name and email metadata 6 | 7 | See https://help.github.com/articles/setting-your-username-in-git/ for instructions. 8 | 9 | == Sign commits with GPG 10 | 11 | See https://github.com/blog/2144-gpg-signature-verification for background and 12 | https://help.github.com/articles/signing-commits-with-gpg/ for instructions. 13 | 14 | == Write well-formed commit messages 15 | 16 | See https://chris.beams.io/posts/git-commit/#seven-rules. 17 | 18 | == Use an editor that supports Editorconfig 19 | 20 | You'll find a link:.editorconfig[`.editorconfig`] file in all bisq-network repositories. These settings ensure consistent management of whitespace, line-endings and more. See http://editorconfig.org for details. 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Bisq Network Documentation 2 | 3 | AsciiDoc sources for the docs hosted at . 4 | 5 | ## New Contributors 6 | 7 | Bisq's [decentralized governance structure][3] makes documentation especially important. If you're interested in contributing: 8 | 9 | - Take a look at [existing docs][4] to get a feel for the general approach to format, tone, and detail 10 | - Look through our [Contributor's Checklist][5] for a background on how we work and conventions (e.g., proper git commit messages) 11 | - Correspond with existing contributors [on Keybase][6] to discuss your ideas or determine where help is most needed 12 | 13 | ## Build 14 | 15 | To build locally, run `./gradlew build` (`gradlew.bat build --project-cache-dir=../cache` on Windows) and then open `build/asciidoc/html5/index.html` in your browser. 16 | 17 | ## Deploy 18 | 19 | Commits pushed to the `master` branch of this repository are automatically built and deployed via Netlify at (permission required). 20 | 21 | ## Writing Tips 22 | 23 | - Keep the [Asciidoctor user manual][1] handy as a reference when editing. 24 | - Install the [Asciidoctor.js Live Preview][2] Chrome extension for instant in-browser rendering of `.adoc` files. This avoids the need to run `gradle build` and then refresh your browser to see the results of your changes. 25 | 26 | [1]: https://asciidoctor.org/docs/user-manual 27 | [2]: https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei 28 | [3]: https://docs.bisq.network/user-dao-intro.html 29 | [4]: https://docs.bisq.network 30 | [5]: https://docs.bisq.network/contributor-checklist.html 31 | [6]: https://keybase.io/team/bisq 32 | -------------------------------------------------------------------------------- /archive.adoc: -------------------------------------------------------------------------------- 1 | = Archive 2 | 3 | * Original <> 4 | * Original <> 5 | * <> 6 | * <> 7 | * <> 8 | * https://docs.google.com/document/d/1DXEVEfk4x1qN6QgIcb2PjZwU4m7W6ib49wCdktMMjLw/edit#heading=h.4nbd0q1s77uq[Bisq arbitration and mediation system] (GDoc) 9 | -------------------------------------------------------------------------------- /backup-recovery.adoc: -------------------------------------------------------------------------------- 1 | = Backup and Recovery 2 | :imagesdir: ./images 3 | :!figure-caption: 4 | 5 | All Bisq data is stored right on your computer. It's never sent to or stored on a central server. That is great for your privacy and security, but it also means backing up your data is your job. This doc shows you how. 6 | 7 | As you use Bisq, you'll accumulate data you will want to save, like your payment accounts, onion address, local reputation, and more. Backing up this data not only protects you in case of unexpected events (e.g., computer crash, data corruption, etc), but it also gives you the flexibility to migrate elements of your Bisq environment to another machine. 8 | 9 | We will start by covering the simplest, most common scenario—backing up and restoring the whole Bisq data directory—and then cover some more advanced use cases by taking a look at what's actually in the data directory. 10 | 11 | IMPORTANT: Backing up your Bisq data directory is different from backing up your Bisq wallet's seed words. While the Bisq data directory includes a complete backup of your Bisq wallet, you should still <>. In a worst-case scenario, even if you can't restore your Bisq data, your seed words will at least allow you to retrieve your funds. 12 | 13 | == Data Directory 14 | 15 | === Back Up 16 | 17 | All Bisq data is stored in one place: 18 | 19 | * macOS: `/Users//Library/Application Support/Bisq` 20 | * Linux: `/home//.local/share/Bisq` 21 | * Windows 7+: `C:\Users\\AppData\Roaming\Bisq` 22 | * Windows XP: `C:\Documents and Settings\\Application Data\Bisq` 23 | 24 | **The safest, quickest, easiest, and most comprehensive thing you can do is to back up this whole folder at regular intervals.** You can either close Bisq and copy this folder to your backup location, or you can export a backup directly to your backup location while Bisq is running from the `Backup` tab of the `Account` screen. 25 | 26 | NOTE: Backup files are not encrypted. If you've set a wallet password, your wallet files will be encrypted, but all your other data will not be. We recommend encrypting the whole backup folder with something like gpg, 7-Zip, Cryptomator, etc. 27 | 28 | === Restore 29 | 30 | First, make sure the Bisq program is closed. And just in case something goes wrong with the restore, back up the current state of your data directory (i.e., the `Bisq` folder) before making any changes. 31 | 32 | Then delete the whole `Bisq` folder and replace it with the `Bisq` folder from your backup. 33 | 34 | === Details 35 | 36 | In your Bisq data directory, you will see a few items. The most notable file is `bisq.log`, which is the Bisq program log file. Checking it can be helpful when you have issues with the Bisq program. 37 | 38 | The other notable item is `btc_mainnet`, which is the main folder containing data for your payment accounts, Tor setup, and wallet. 39 | 40 | == Payment Accounts 41 | 42 | There are 2 components to payment accounts on Bisq: account details and account aging. 43 | 44 | **Account details** consist of all the payment methods you've set up and their associated account numbers, bank information, addresses, etc. You can export this data from within Bisq on the `National currency accounts` and `Altcoin accounts` tabs of the `Account` screen. Click `Export accounts` and Bisq will output a file that you can use to import these details later. 45 | 46 | **Account aging** is a measure to reduce fraud risk for fiat payments. Newer accounts have lower trading limits. It takes 3 months for a payment account to reach the maximum trading limit. See more details on account aging <>. Note that account aging does not apply to altcoin accounts since they don't have chargeback risk. 47 | 48 | To restore account details, simply import the file you exported earlier through the same interface. 49 | 50 | To include account aging with your account details import, you will also need to replace the `btc_mainnet/keys/sig.key` file with the `sig.key` file from your backup. Be sure you don't have any open offers, trades, or disputes before changing `sig.key`, otherwise you won't be able to respond to those activities. 51 | 52 | If you don't have an account export file, but you have a full backup of the data directory, you can still fully restore your account details and account aging by manually copying the following files to your data directory from a backup: 53 | 54 | * `btc_mainnet/db/UserPayload` (account details and salt) 55 | * `btc_mainnet/keys/sig.key` (key for signing p2p messages) 56 | 57 | **Again, please make sure you don't have any open offers, trades, or disputes before changing `sig.key`.** 58 | 59 | IMPORTANT: Before manually making any changes to Bisq data files, please ensure that the Bisq program is closed and that you have backed up the current state of your Bisq data directory. 60 | 61 | == Tor State 62 | 63 | Bisq runs as a Tor hidden service to protect your privacy. 64 | 65 | [.float-group] 66 | -- 67 | 68 | [.right.text-center] 69 | .Local reputation. 70 | image::repeat-trading-peer.png[Local reputation,300,300] 71 | 72 | As you do trades, you'll build _local reputation_ whereby Bisq will show you how many trades you've completed with other peers. The idea is that if a trade with someone went well, it's reasonable to expect your next trade with that person will go well too, creating a rudimentary sort of reputation indicator while maintaining anonymity. 73 | 74 | This mechanism is tied to your onion address. You'll see it when browsing open offers: Bisq will add a bubble next to the avatars of peers you've previously traded with indicating how many times you've already traded with them. 75 | 76 | -- 77 | 78 | If you want to carry over a particular onion address (and keep your local reputation), you can replace the `btc_mainnet/tor/hiddenservice` folder in your data directory with the one from your backup. 79 | 80 | If you want to change your onion address, just delete the `btc_mainnet/tor/hiddenservice`. The next time you start Bisq, you will have a different onion address. You'll lose your local reputation, but you'll gain privacy since you will appear as a new trader on the network. That means your past trading partners will no longer be able to recognize that your new offers are from _you_. 81 | 82 | **Make sure you don't have any open offers, trades, or disputes before changing your onion address, as doing so will make you unreachable.** 83 | 84 | IMPORTANT: Before manually making any changes to Bisq data files, please ensure that the Bisq program is closed and that you have backed up the current state of your Bisq data directory. 85 | 86 | == Wallet Data 87 | 88 | Your wallet data is stored in `btc_mainnet/wallet`. There are 3 primary ways to work with wallet backup files to resolve wallet issues. 89 | 90 | === Resync SPV chain 91 | 92 | Wallet issues (e.g., incorrect balance showing, corrupted/out-of-sync SPV file) can often be solved by resyncing the SPV chain and restarting the Bisq program. You can do this by clicking the `Delete SPV file and resync` button on the `Network info` tab of the `Settings` screen. If you can't access this screen, you can just delete the `bisq.spvchain` file in `btc_mainnet/wallet` (just be advised that you will need to manually restart Bisq twice to complete the resync). 93 | 94 | The SPV file is a collection of data from the Bitcoin blockchain that tells Bisq your wallet's balances. All data in the file is available on the Bitcoin network. Deleting this file just forces Bisq to resync with the Bitcoin network and fetch the data it needs to determine your balances again. 95 | 96 | NOTE: Resyncs can take a while, depending on how old your wallet is and how many transactions you did with it. Your CPU may run at 100% and Bisq will appear unresponsive. This is normal. Be patient! 97 | 98 | === Restore wallet backup 99 | 100 | If issues persist, you can try to restore a wallet backup file from `btc_mainnet/wallet/backup/backups_bisq_BTC_wallet`. This folder holds your most recent wallet backups made on a rolling basis. Replace the `bisq_BTC.wallet` wallet file in `btc_mainnet/wallet` with a recent wallet backup file and rename it to `bisq_BTC.wallet`. You'll also need to resync the SPV chain, so be sure to delete `bisq.spvchain` when restoring a wallet backup. 101 | 102 | Start Bisq and see if your issue is fixed. If not, repeat with another wallet backup file. 103 | 104 | === Switch to a new data directory 105 | 106 | If neither resyncing the SPV file nor restoring a wallet backup solves the problem, you might have a corrupted wallet. In this case, it's best to switch to a new data directory and start using a new wallet. 107 | 108 | NOTE: Bisq SPV wallets use the bitcoinj library. This library is not built well for high performance, and the wallet file gets larger with more transactions, to the point disk write errors become a real threat (which can corrupt the wallet file) and performance can suffer (e.g., long startup times if you haven't started Bisq in a while). For these reasons, you may want to consider switching to a new data directory after a while even if you're not having issues at the moment. 109 | 110 | First, make sure you don't have any open offers, trades, or disputes, as you won't be able to respond to these activities afterward. Then, send any funds in your Bisq wallet to an external wallet (either through a regular transaction from the `Funds` screen, emergency wallet tool with Ctrl/Cmd + E, or by restoring from seed words with a tool like Electrum). 111 | 112 | Once you've retrieved your funds, here's how to generate a new data directory: 113 | 114 | * close Bisq 115 | * delete the whole `Bisq` directory (after backing it up, just in case) 116 | * start Bisq (this will generate a fresh new data directory) 117 | * send your funds back into Bisq 118 | * optional: restore payment accounts and/or Tor keys through the processes outlined above 119 | 120 | **Make sure you don't have any open offers, trades, or disputes before doing this.** 121 | 122 | IMPORTANT: Before manually making any changes to Bisq data files, please ensure that the Bisq program is closed and that you have backed up the current state of your Bisq data directory. 123 | 124 | == Trade History 125 | 126 | You can export your trade history for your own records in CSV format on the `History` tab of the `Portfolio` screen. Note that there is no way to import this data. 127 | -------------------------------------------------------------------------------- /bisq-mobile.adoc: -------------------------------------------------------------------------------- 1 | = Bisq Mobile 2 | :imagesdir: images 3 | :!figure-caption: 4 | 5 | There are a couple of efforts underway to enable mobile functionality for Bisq. One of those efforts is mobile notifications, and it's ready to use today. 6 | 7 | == Mobile notifications 8 | 9 | The Bisq mobile notifications app lets you get notifications from Bisq desktop on your iPhone or Android device. Here we explain how to set it up and how it works. 10 | 11 | === 1. Get the app 12 | 13 | * iOS: https://itunes.apple.com/us/app/bisq-mobile/id1424420411[App Store^] (https://github.com/joachimneumann/bisqremote_iOS[source^]) 14 | * Android: https://play.google.com/store/apps/details?id=com.joachimneumann.bisq[Play Store^] (https://github.com/joachimneumann/bisqremote_Android[source^]) 15 | 16 | === 2. Pair it with Bisq desktop 17 | 18 | [.float-group] 19 | -- 20 | 21 | [.right.text-center] 22 | .Scan QR code or paste it in. 23 | image::mobile-notifications-setup.png[Scan QR code or paste it in,400,400] 24 | 25 | In your desktop Bisq app, go to the `Account` screen and click on `Notifications`. There, click on `Scan QR code`. 26 | 27 | In the mobile app, click `Pair` and then scan the QR code with your computer's webcam. 28 | 29 | [NOTE] 30 | If you don't have a webcam, click the `I don't have a webcam` button in desktop Bisq. Then send the pairing string on your mobile device to your computer and paste it in the `Pairing token` field. 31 | 32 | Once pairing completes, you'll see a success message, and can then proceed to the next screen to configure notifications. 33 | -- 34 | 35 | === 3. Configure notifications 36 | 37 | There are three types of notifications you can get: trade alerts, offer alerts, and price alerts. You can also enable and disable notification sounds. 38 | 39 | ==== Trade alerts 40 | 41 | To enable trade alerts, simply check the `Receive trade messages` box. 42 | 43 | Once enabled, you will get a notification when: 44 | 45 | * your action is needed on any open trades 46 | * one of your offers is taken 47 | * you've received a new dispute message 48 | 49 | Note that dispute alerts do not include any message content—they merely let you know a new dispute message has been received on your desktop Bisq app. 50 | 51 | Here's how trade alerts can be useful: 52 | 53 | Example 1: you're buying BTC, just sent your deposit, and are waiting for the transaction to hit 1 blockchain confirmation so you can send payment. That can take approximately 10 minutes. Instead of waiting at your screen, you can go have a coffee and let your phone alert you when it's time to send the fiat currency or altcoin payment. 54 | 55 | Example 2: you're selling BTC, and you're waiting for your trading partner to send you fiat currency or altcoin payment. It might take them minutes or hours. Instead of repeatedly checking your desktop Bisq app for updates, your mobile device will simply push an alert as soon as your trading partner marks their payment as sent, so you can then check for the payment and promptly complete the trade. 56 | 57 | [WARNING] 58 | Please don't rely on mobile notifications to receive important messages. Mobile notifications are new and there may be bugs. Please be sure to still check your desktop Bisq app for trade status, dispute messages, etc! 59 | 60 | ==== Offer alerts 61 | 62 | [.float-group] 63 | -- 64 | 65 | [.right.text-center] 66 | .Set offer alert criteria. 67 | image::configure-offer-alert.png[Set offer alert criteria,400,400] 68 | 69 | If enabled, you will get alerts whenever there's a new offer that fits your criteria. 70 | 71 | To set your criteria: 72 | 73 | 1. Select your preferred payment account. 74 | 75 | 2. Then select which offers you want to receive alerts for: buy or sell. If you want to buy bitcoin, you'll want to know when someone's made a good sell offer (and vice-versa if you want to sell bitcoin). 76 | 77 | 3. Determine the % distance from the market price for which you want to get a notification. With a price distance set, you will only receive an alert when an offer that meets (or exceeds) your requirements is published. Example: you want to sell BTC, but you will only sell at a 2% premium to the current market price. Setting this field to 2% will ensure you only receive alerts for offers with prices that are 2% (or more) above the current market price. 78 | 79 | 4. Hit `Add offer alert`. 80 | -- 81 | 82 | Clicking the `Manage offer alerts` button shows you a screen with all configured alerts. There, you can remove offer alerts you no longer need. 83 | 84 | ==== Price alerts: 85 | 86 | [.float-group] 87 | -- 88 | 89 | [.right.text-center] 90 | .Set price alert criteria. 91 | image::configure-price-alert.png[Set price alert criteria,400,400] 92 | 93 | If enabled, you'll get alerts when bitcoin hits the specified price in the specified currency. 94 | 95 | First, select your currency. Then, choose the upper and lower price thresholds. You'll get an alert when the bitcoin price goes above your upper threshold, or when it goes below your lower threshold. 96 | 97 | Example: an alert set with an upper threshold of 6000 EUR and lower threshold of 5500 EUR will send you a notification when the market price goes over 6000 _or_ when it goes below 5500 EUR. 98 | -- 99 | 100 | [NOTE] 101 | Once a price alert is triggered, it's automatically deleted so you don't get repeated notifications as the price fluctuates. 102 | 103 | === 4. Technical details & privacy: 104 | 105 | .Bisq mobile notification architecture: The notifications are sent from the Bisq desktop app to the Bisq relay node which acts as proxy to the Apple/Google Push Notification Service. 106 | image::mobile-notifications-architecture.png[mobile-notifications-architecture,600,600] 107 | 108 | ==== Pairing 109 | 110 | Before allowing the mobile app to start the pairing to the Bisq desktop app, the mobile App registers with 111 | the Apple or Google notification service and receives a notification token. 112 | This happens in the background without any user interaction. 113 | Next, a byte cryptographic key for symmetric encryption is generated in the phone and the pairing token is assembled. 114 | [NOTE] 115 | We use the 128 bit AES/CBC/PKCS5Padding symmetric encryption algorithm. 116 | A fresh 16-character Initialization Vector is created and attached to each notification. 117 | 118 | The pairing token consists of four parts which are separated by the "|" character: 119 | 120 | * A Magic, currently one of iOS, iOSDev or android 121 | * A Phone descriptor, e.g., iPhone6 122 | * A 32 byte cryptographic key for symmetric encryption. This key is generated by the phone and used in the Bisq desktop app to encrypt the content of the notification. 123 | * A device token, either from Apple or from Google. 124 | 125 | The pairing token is then transferred from the phone to the Bisq Desktop app by QR code (using the computers' webcam) or as a string (by email). 126 | 127 | ==== Sending a notification 128 | 129 | The Bisq desktop app knows the device token (from Apple or Google) and it has the encryption key from the phone. 130 | The notification itself is a json string containing the type of notification and its content. 131 | After encrypting the notification the desktop app sends it along with the device token to a 132 | Bisq relay node over Tor. Because of Tor, the relay node does not know the IP address of the computer on which you run your Bisq desktop app. 133 | The relay node forwards the notification to an Apple/Google push notification server (over https), 134 | which then pushes a notification to your mobile device using the provided device token. 135 | 136 | ==== Privacy 137 | 138 | Ultimately, Apple/Google know that a device with your device token is receiving Bisq notifications. 139 | Note that they already knew you are likely to be a Bisq user when you download the Bisq mobile app. 140 | However, neither Google nor Apple can see the content of the notification. This is also the reason why 141 | OS pop-ups that notify you cannot contain any notification specific content. 142 | 143 | Currently, the relay node does not store any data (notifications, device tokens, etc). 144 | 145 | We feel that Push notifications can't be implemented in a more private way. 146 | If there is any aspect of this mobile notifications mechanism, feel free to contact us. 147 | Of course, the notification mechanism is optional and does in no way limit the functionality of the Bisq desktop app. 148 | 149 | ==== Source Code 150 | The iOS and Android mobile apps are open source: 151 | 152 | * https://github.com/joachimneumann/bisqremote_iOS[iOS app] 153 | * https://github.com/joachimneumann/bisqremote_Android[Android app] 154 | * https://github.com/joachimneumann/bisqremote[java app to test notification creation] 155 | 156 | See the https://github.com/joachimneumann/bisqremote/wiki/Specification[git wiki] for additional technical details. 157 | -------------------------------------------------------------------------------- /btcnode.adoc: -------------------------------------------------------------------------------- 1 | = Bitcoin Core Nodes 2 | 3 | Bisq contributors run a federation of Bitcoin Core nodes to (1) avoid relying on bloom filters to protect user privacy when connecting to arbitrary public nodes and (2) ensure Bisq connects to nodes with consistent Bitcoin Core implementations. 4 | 5 | 6 | == Introduction 7 | 8 | In the past, Bisq connected to arbitrary Bitcoin Core nodes, but the prospect of the SegWit2x hard fork in Fall 2017 made it clear this was not ideal—in the case of a hard fork, it would be impossible for Bisq to tell which fork a connected node was running. The SegWit2x hard fork never happened, but if it did, there was a chance transactions would execute on an undesirable fork, and even worse, a chance that transactions would execute on different forks. 9 | 10 | Critically, bloom filters introduce serious privacy flaws when connecting to arbitrary bitcoin nodes, as chain analysis companies spy on SPV wallets. Connecting only to nodes run by trusted Bisq contributors avoids such monitoring. 11 | 12 | Hence the decision to run a federation of Bitcoin nodes: more robust user privacy and a consistent Bitcoin Core implementation Bisq can rely on. 13 | 14 | Note: Bisq users can still choose to connect to arbitrary public nodes, as before, or even connect to specific nodes they prefer. 15 | 16 | == Infrastructure 17 | 18 | === GitHub 19 | 20 | Issues are managed in the {gh-org}/bisq-btcnode[bisq-network/bisq-btcnode] repository. 21 | 22 | === Slack 23 | 24 | Discussion of Bitcoin Core node status and updates takes place in the `#bisq-btcnode` Slack channel. 25 | 26 | 27 | == Roles 28 | 29 | 30 | === Maintainer 31 | 32 | The contributor(s) responsible for full node <> and <>.footnote:[See link:roles.html#maintainer[]] 33 | 34 | ==== Role Issue 35 | 36 | {gh-org}/roles/issues/66[bisq-network/roles#66] footnote:[See link:roles.html#issue[]] 37 | 38 | ==== Role Team 39 | :btcnode-maintainers: {gh-team}/btcnode-maintainers[@bisq-network/btcnode-maintainers] 40 | 41 | {btcnode-maintainers} footnote:[See link:roles.html#team[]] 42 | 43 | ==== Duties 44 | 45 | * Monitor communications on the `#bisq-btcnode` Slack channel.footnote:[See link:roles.html#communication[]] 46 | * Keep this documentation up to date (in particular, the <> detailed below).footnote:[See link:roles.html#documentation[]] 47 | * Write a monthly report on the Bitcoin Node Maintainer <>.footnote:[See link:roles.html#reporting[]] 48 | 49 | ==== Rights 50 | 51 | * Write access to the {gh-org}/bisq-btcnode[bisq-network/bisq-btcnode] repository. 52 | 53 | === Operator 54 | 55 | The contributor(s) responsible for keeping full nodes running as outlined in <>.footnote:[See link:roles.html#maintainer[]] 56 | 57 | ==== Role Issue 58 | 59 | {gh-org}/roles/issues/67[bisq-network/roles#67] footnote:[See link:roles.html#issue[]] 60 | 61 | ==== Role Team 62 | :btcnode-operators: {gh-team}/btcnode-operators[@bisq-network/btcnode-operators] 63 | 64 | {btcnode-operators} footnote:[See link:roles.html#team[]] 65 | 66 | ==== Duties 67 | 68 | * Operate bitcoin nodes as detailed below in <>. 69 | * Monitor communications on the `#bisq-btcnode` Slack channel.footnote:[See link:roles.html#communication[]] 70 | * Write a monthly report on the Bitcoin Node Operator <>.footnote:[See link:roles.html#reporting[]] 71 | 72 | ==== Rights 73 | 74 | * N/A 75 | 76 | 77 | == Process 78 | 79 | === Step 0. Evaluate 80 | 81 | Determine if this is really a role you can fill. It's expected that your node will maintain (1) good uptime and (2) an up-to-date config and bitcoind version (as required by the Bitcoin Node Maintainer). There are no strict requirements for either, but it's expected that you will make your best effort to stay current. 82 | 83 | === Step 1. Get in Touch 84 | 85 | Contact the Bitcoin Core Maintainer to convey your intention of setting up a Bitcoin Core node for Bisq. 86 | 87 | === Step 2. Set it Up 88 | 89 | Set up a Bitcoin Core node, making sure to use the configuration https://github.com/bisq-network/bisq-btcnode/blob/master/bitcoin.conf[specified here]. Also make sure your node runs in a secure environment (i.e. basic server admin: locked-down user access, security patches applied promptly, etc) and that it allows onion connections so Bisq can connect to it. 90 | 91 | === Step 3. Include Node in Bisq Source 92 | 93 | Once your node is ready, send a PR to include it as a Bitcoin Core node for Bisq (they're currently specified https://github.com/bisq-network/bisq/blob/master/core/src/main/java/bisq/core/btc/nodes/BtcNodes.java[here]). 94 | -------------------------------------------------------------------------------- /build.gradle: -------------------------------------------------------------------------------- 1 | plugins { 2 | id 'org.asciidoctor.convert' version '2.3.0' 3 | } 4 | 5 | asciidoctor { 6 | sourceDir = file('.') 7 | 8 | resources { 9 | from(sourceDir) { 10 | include '**/*.png' 11 | include '**/*.svg' 12 | include '**/*.ico' 13 | exclude 'build/**' 14 | } 15 | } 16 | 17 | attributes 'source-highlighter': 'coderay', 18 | toc : 'left', 19 | sectanchors : '', 20 | icons : 'font', 21 | idprefix : '', 22 | idseparator : '-', 23 | docinfo : 'shared@', 24 | 'gh-org' : 'https://github.com/bisq-network', 25 | 'gh-team' : 'https://github.com/orgs/bisq-network/teams', 26 | 'role' : 'docs', 27 | 'stylesheet' : 'bisq.css', 28 | 'stylesdir' : './css@', 29 | 'docinfodir' : './@' 30 | } 31 | 32 | build.dependsOn asciidoctor 33 | -------------------------------------------------------------------------------- /compensation.adoc: -------------------------------------------------------------------------------- 1 | = Requesting Compensation and Voting 2 | :imagesdir: ./images 3 | :!figure-caption: 4 | 5 | Have you contributed to the Bisq Network? Great, and thank you! Here is how to request compensation for your work, and vote on requests from others. 6 | 7 | If you're not sure how to start contributing, check out our <> for tips on getting started and figuring out what to work on. 8 | 9 | == Background 10 | 11 | Compensation requests are generally made for work done in the current DAO cycle—after the end of the last proposal phase, and before the end of the current one—but you can make a request for work done any time in the past. 12 | 13 | IMPORTANT: Compensation requests can only be made for _delivered work_. Work that's planned or in-progress is not eligible for compensation. See more on what that means https://github.com/bisq-network/proposals/issues/19[here^]. Generally, work merged to the master branch of a repository https://github.com/bisq-network/proposals/issues/38[can be considered delivered^] (if applicable). 14 | 15 | Each DAO cycle is roughly 1 month long, but timing is based on the Bitcoin block height, so exact dates for the start & end of DAO cycles vary. 16 | 17 | Make sure you check the Bisq DAO dashboard to get an idea of the submission deadline for the current cycle: 18 | 19 | .Estimated timeframe for Bisq DAO Cycle 2. 20 | image::check-dao-timing.png[Estimated timeframe for Bisq DAO Cycle 2] 21 | 22 | Block confirmation times can vary quite a bit, so keep an eye on these dates, and don't wait until the last minute! 23 | 24 | You must file a compensation request before the end of the current proposal phase in order to have it evaluated in the current voting cycle. If you miss it, don't worry—you can submit your request in the next proposal phase. 25 | 26 | == Submit your compensation request 27 | 28 | === List your work in a new GitHub issue 29 | 30 | Making compensation requests and voting takes place in the Bisq DAO, but data stored there is minimized to decrease the burden on the peer-to-peer network (and on the Bitcoin network). 31 | 32 | Hence the GitHub issue. All the details of what work you did and why it's valuable can get long, so you'll put those details in a GitHub issue, and then _link_ to that issue in your compensation request on the Bisq DAO. 33 | 34 | ==== Create the issue 35 | 36 | The issue should go in the https://github.com/bisq-network/compensation[bisq-network/compensation^] repository, and it should be titled in the following format: 37 | 38 | `For Cycle N` 39 | 40 | Where N is the number of the current cycle. Please stick to this convention—it's cleaner and much easier to track when looking back in time. 41 | 42 | 43 | ==== List your work 44 | 45 | Your issue needs to convince Bisq stakeholders _what_ you did, _how much_ it's worth, and _why_ it's valuable. 46 | 47 | In order to make your case as strong as possible, your request should include the following information: 48 | 49 | - The total amount you are requesting in BSQ 50 | - Links to issues, pull requests, and other "evidence" for any work you want to be compensated for 51 | - Comments that help explain what the work is, why it is valuable, etc. 52 | - Links to role reports, if you hold any roles in the Bisq network 53 | 54 | IMPORTANT: This is a big reason that it's critical that everything you do for Bisq be as public, verifiable, and documented as possible, and that everything you do has positive consensus with multiple stakeholders so you know you're not wasting your time. 55 | 56 | Even then, not all stakeholders will be familiar with your work, so it's important to be as thorough as you can when making a compensation request so there's enough context for those unfamiliar with your work to make an informed vote. 57 | 58 | ==== Value your work 59 | 60 | As mentioned above, Bisq contributions are only eligible for compensation once delivered. For code, that means _merged to master_, and for non-code contributions that means _already delivered_. How you determine the value you request is up to you, but it should be based on the value of the contribution you made, not on the raw time you spent. 61 | 62 | A good rule of thumb, if you are unsure about the value of your contribution: consider what you would charge for your work if you did it as a freelancer. 63 | 64 | For example, it might be reasonable to request 50 BSQ for fixing some typos in a doc. But requesting 1000 BSQ for that same task, just because it took you a few hours to read through the doc, will probably be rejected. 65 | 66 | See the current BSQ price, open trades, trade history and other information on the https://bisq.network/markets/?currency=bsq_btc[Bisq Markets^] page. 67 | 68 | See https://github.com/bisq-network/compensation/issues/277[this link^] for an example compensation request. 69 | 70 | ==== Wait for team lead review ==== 71 | 72 | Per the https://bisq.wiki/Compensation[compensation request review process], your compensation request will be reviewed by the team lead(s) responsible for the work you delivered. You may be asked for further information or to revise your compensation request. For this reason, **please do not submit your compensation request to the DAO in the next step until this review process is complete!** 73 | 74 | === File your compensation request in the DAO 75 | 76 | When the team lead review process is complete, you're ready to file your request for DAO voting. 77 | 78 | BSQ is issued on Bisq when a compensation request is approved through DAO voting, so your compensation request needs to be filed there in order for you to actually be paid. 79 | 80 | Once you've documented all details of your request in a new issue on GitHub, make a new compensation request proposal on Bisq: 81 | 82 | .Make a new compensation request in the Bisq DAO. 83 | image::make-compensation-request.png[Make a new compensation request in the Bisq DAO] 84 | 85 | Make sure you select `Compensation request` as the proposal type. Also make sure you use a name that stakeholders will recognize (or at least one they can cross-reference with your other online profiles like GitHub, Keybase, forum, etc). 86 | 87 | For the proposal link, be sure to use this format: `https://bisq.network/dao-compensation/\#`, where `#` is the number of your GitHub issue. For example, if your compensation request's GitHub URL is `https://github.com/bisq-network/compensation/issues/33`, the URL in your DAO compensation request should be `https://bisq.network/dao-compensation/33`. Don't copy the GitHub link directly—it won't work! 88 | 89 | [NOTE] 90 | .Why not just use GitHub links? 91 | ==== 92 | Bisq may not use GitHub forever. But the Bitcoin blockchain is forever, and proposal URLs cannot be changed—the Bitcoin transaction corresponding to a Bisq DAO proposal includes a hash of the proposal's data object, which includes the proposal URL. This is why Bisq proposals require a URL with a domain name that Bisq controls: if proposal data ever needs to be migrated, the links can remain the same. 93 | ==== 94 | 95 | When you're ready, click `Make proposal` to confirm your proposal for voting in the current cycle. **Proposal data cannot be edited**, so make sure everything is correct, especially the amount you're requesting. 96 | 97 | If you need to make a change, you can delete the proposal and make a new one while the proposal phase is still active, but you'll need to pay the proposal fee again. Once the proposal phase is over, proposals cannot be added or removed until the next proposal phase. 98 | 99 | NOTE: A compensation request is a type of proposal, and proposals cost a fee to make in the Bisq DAO. Currently that fee is 2 BSQ. Since a compensation request is intended to issue new BSQ, you'll also need to include a small amount of bitcoin to be colored into BSQ if your proposal is accepted—100 satoshis × [requested BSQ amount]. See more details in our https://docs.bisq.network/dao-user-reference.html#proposal-phase[User Guide]. 100 | 101 | The BSQ and BTC is automatically added to your proposal transaction by Bisq, but the BTC needs to be in your Bisq BTC wallet. Make sure you have enough in there before making your request. Keep in mind that you'll also need some BSQ and BTC for the other proposal phases (vote & vote reveal). 102 | 103 | When you successfully submit your proposal in the DAO, it'll propagate across the Bisq peer-to-peer network and be ready for stakeholders to vote on in the voting phase. If your request is approved, you will see the BSQ you requested in your wallet after the voting phase is over. 104 | 105 | == Vote on requests from others 106 | 107 | It's not strictly necessary to vote on others' proposals, but highly encouraged that all stakeholders take part in decision-making for the network. 108 | 109 | You can see how to take part in voting and the rest of the DAO cycle https://docs.bisq.network/getting-started-dao.html#participate-in-a-voting-cycle[here]. 110 | 111 | == Questions 112 | 113 | If something doesn't make sense, don't hesitate to reach out. There's a community of people to help you on https://keybase.io/team/bisq[Keybase^], the https://bisq.community/[Bisq forum^], and the https://www.reddit.com/r/bisq/[/r/bisq subreddit^]. 114 | 115 | == Learn more 116 | 117 | BSQ is a core element of Bisq's governance mechanism, allowing contributors and users to have a hand in crafting the strategy of the project through a voting process. 118 | 119 | You can learn more about the overall mechanism in <> and https://www.youtube.com/playlist?list=PLFH5SztL5cYPAXWFz-IMB4dBZ0MEZEG_e[these videos^]. 120 | 121 | Our <> covers more practical details on using the Bisq DAO, and our <> covers technical details. Check out <> for all Bisq DAO resources. 122 | -------------------------------------------------------------------------------- /contributor-checklist.adoc: -------------------------------------------------------------------------------- 1 | = Contributor Checklist 2 | 3 | So you're interested in contributing to Bisq--welcome! This checklist will get you plugged in and productive as quickly as possible. 4 | 5 | [NOTE] 6 | .Who is a contributor? 7 | ==== 8 | Bisq is free and open source software, but contributing is _not_ just about writing code. *A contributor is any individual who works to improve and add value to the Bisq Network and its users.* 9 | 10 | This can mean anything from fixing typos in documentation, to answering questions on the Bisq Forum, to implementing new Bisq features and everything in-between. All such contributions are eligible for compensation under the Bisq DAO. See more details <<#do-valuable-work-and-get-compensated,below>> and in the <> doc. 11 | ==== 12 | 13 | == Say hello and get started 14 | 15 | [%interactive] 16 | 17 | * [ ] Join our https://keybase.io/team/bisq[Keybase team]. 18 | 19 | * [ ] Introduce yourself in the `#introductions` channel. Say a bit about your skills and interests. This will help others point you in the right direction. 20 | 21 | * [ ] Explore the other channels on Keybase, and join the ones that are of interest to you. For a start, we recommend joining `#proposals`, `#growth`, `#roles`, `#compensation`, `#dev` and `#dev-onboarding` (if you're a developer). 22 | 23 | * [ ] Watch the https://github.com/bisq-network/proposals[proposals], https://github.com/bisq-network/roles[roles] and https://github.com/bisq-network/compensation[compensation] repositories to get notified of threaded GitHub issue discussions that happen there. 24 | 25 | * [ ] Read the https://github.com/bisq-network/bisq/blob/master/docs/README.md[developer docs] to set up a Bisq development environment. 26 | 27 | * [ ] Read https://chris.beams.io/posts/git-commit[How to Write a Git Commit Message] and follow its https://chris.beams.io/posts/git-commit#7-rules[7 rules] when contributing to Bisq projects. 28 | 29 | * [ ] Get set up to https://help.github.com/articles/signing-commits-using-gpg/[Sign your Git Commits] with GPG. 30 | 31 | == Learn how we work 32 | 33 | [%interactive] 34 | 35 | * [ ] Read about Bisq's https://bisq.wiki/Project_management[project management process]. 36 | 37 | * [ ] Familiarize yourself with https://rfc.unprotocols.org/spec:1/C4/[C4: The Collective Code Construction Contract]. It's a simple set of collaboration rules based on GitHub's fork+pull request model, and a foundational part of how we work together. 38 | 39 | * [ ] For more context on C4 and the principles behind it, read author Pieter Hintjens' short book, https://legacy.gitbook.com/book/hintjens/social-architecture/details[Social Architecture]. 40 | 41 | * [ ] Introduce yourself to Bisq and the Bisq DAO with the <> doc. It's a bit outdated now, as the DAO has been launched, but it's the best overview of Bisq's background and underlying concepts. 42 | 43 | * [ ] To understand Bisq's commitment to _radical transparency_ and _radical honesty_, read Part III of Ray Dalio's https://www.amazon.com/Principles-Life-Work-Ray-Dalio/dp/1501124021/[Principles]. 44 | 45 | * [ ] To get inspired about what building software in a non-hierarchical organization can be like (and what it requires of everyone involved), read the http://www.valvesoftware.com/company/Valve_Handbook_LowRes.pdf[Valve Employee Handbook]. 46 | 47 | == Get connected 48 | 49 | [%interactive] 50 | 51 | * [ ] Subscribe to the https://www.youtube.com/c/bisq-network[Bisq YouTube channel] to get notified about every meeting we hold, tutorial we publish, live session we broadcast, and more. 52 | 53 | * [ ] Follow https://twitter.com/bisq_network[@bisq_network] on Twitter. 54 | 55 | * [ ] Catch up on past https://www.youtube.com/playlist?list=PLFH5SztL5cYOtcg64PntHlbtLoiO3HAjB[Bisq Tech Session] YouTube live streams. 56 | 57 | * [ ] Subscribe to the https://lists.bisq.network/listinfo/bisq-contrib[bisq-contrib] mailing list for low-frequency, high-priority contributor communications. 58 | 59 | == Getting assigned to an issue or role 60 | 61 | Discuss with others, and after it is agreed that someone will assign something to you, do the following: 62 | 63 | * [ ] Request an invite to the https://github.com/bisq-network[@bisq-network] organization. An admin will get you set up. Doing this makes it possible to add you to the https://github.com/orgs/bisq-network/people[@bisq-network/people] team and to assign you to GitHub issues. 64 | 65 | * [ ] After accepting your GitHub invitation, please change your https://github.com/orgs/bisq-network/people[membership visibility] from `private` to `public`. This helps others know at a glance roughly how many contributors are involved with Bisq. 66 | 67 | == Do valuable work and get compensated 68 | Ok. You're all set up and ready to work. Here's what to do next. 69 | 70 | . *Find a problem somewhere in Bisq-land* that (a) needs fixing and (b) is a match for your skills and interests. Browse https://bisq.wiki/Critical_Bugs[critical bugs], open bounties, ask around about what other contributors think needs fixing. Because while you don't need anybody's permission and you can work on whatever you want, you'll want to know up front whether anybody else is going to care about the work you do. 71 | 72 | [sidebar] 73 | .More on finding work to do 74 | -- 75 | It is not required to work on an existing bounty issue to contribute to Bisq, and no one is here to tell you what to do. Contributors who have their own ideas are free to work in their own forks on whatever they wish, however they wish, and without any permission from Bisq stakeholders. 76 | 77 | With that said, it's a good idea to consult with stakeholders via Keybase, GitHub, the mailing list, or other communication channels before setting out on any serious contribution effort. Do this in order to ensure your contribution is: 78 | 79 | . something that the relevant maintainer(s) would be likely to merge; 80 | . something that stakeholders would likely vote to approve as a compensation request; 81 | . subjected to as much feedback as possible while still an idea and thus cheap to change or abort. 82 | 83 | Remember: _every contributor_ is free to work on what they want, including maintainers who may or may not want to review and merge your pull request if they don't have any prior context for it, or reason to believe it's worth spending their time on. 84 | -- 85 | 86 | [start=2] 87 | . *Do work to fix that problem.* Submit your fix for review with a pull request (for code and documentation changes) or with a GitHub issue (for everything else). 88 | 89 | . *Request that others review your work.* The best way to do this is by writing good commit comments and pull request/issue descriptions that clearly explain the problem your work is intended to solve, why it's important, and why you fixed it the way you did. Make it as easy as possible for others to review your work. Make it a _pleasure_ for others to review your work. 90 | 91 | . *Incorporate review feedback* you get until your fix gets merged or is otherwise accepted. 92 | 93 | . *Repeat* steps 1–4. 94 | 95 | . <> at the end of the month, link to your finished work and request the amount of https://docs.bisq.network/dao/phase-zero.html#the-bisq-dao-and-bsq-token[BSQ] you believe that work to be worth to Bisq, the Bisq Network and its users. 96 | 97 | [TIP] 98 | .Reviews are for everybody 99 | If you want to be really popular around here, don't just submit your own work, but also spend time reviewing the work of others. And remember: reviews are eligible for compensation just like any other contribution. 100 | -------------------------------------------------------------------------------- /dao-user-reference.adoc: -------------------------------------------------------------------------------- 1 | = Bisq DAO User Reference 2 | :imagesdir: ./images 3 | :!figure-caption: 4 | 5 | Practical details on the workings of the Bisq DAO for traders and contributors. 6 | 7 | Some basic DAO functions may not be conceptually complex—e.g., paying trading fees, making proposals, voting, etc—but implementing these functions on peer-to-peer networks (Bitcoin and Bisq's own P2P network) adds extensive technical complexity. 8 | 9 | Immense technical challenges aside, the practical constraints of the Bisq DAO are not trivial. One requirement is true, complete decentralization of decision-making (no persons with special powers) and funding (no central wallets or accounts to store and distribute funds). Another is that incentives must be so well-aligned that stakeholders are naturally motivated to grow and support the DAO merely by acting rationally—there are no managers to promote you (or fire you). 10 | 11 | And perhaps most critically, the DAO needs to be secure: safe from hackers and scammers trying to take advantage of the DAO and its users. 12 | 13 | == BSQ Token 14 | 15 | Contributors earn BSQ for working on Bisq, and traders spend BSQ to trade on Bisq. We've covered this basic dynamic in <> and https://www.youtube.com/watch?v=pNvOZlIDYEQ&list=PLFH5SztL5cYPAXWFz-IMB4dBZ0MEZEG_e[this video series^]. 16 | 17 | But what actually _is_ BSQ, and where does it come from? 18 | 19 | === More About BSQ 20 | 21 | A single BSQ token is denominated as 100 satoshis (i.e., it's represented on the Bitcoin blockchain as 0.00000100 BTC). This bitcoin is 'colored' with additional properties that causes Bisq software to recognize it as BSQ. 22 | 23 | BSQ can only be created in one of two ways: 24 | 25 | 1. through the genesis distribution (detailed below) 26 | 2. through an issuance transaction (compensation request or reimbursement request) 27 | 28 | While BSQ is just bitcoin, it should only be stored in a Bisq wallet. 29 | 30 | [sidebar] 31 | .Warning 32 | -- 33 | WARNING: **Please do not try to send BSQ to a non-Bisq wallet, or to otherwise create your own BSQ transactions**. The rules to form a valid BSQ transaction are rather complex, and even the slightest error can result in invalid BSQ. Even the <> does not cover every single detail—the only complete reference is the source code. Also note that future code changes may break custom transactions or implementations. Bisq will NOT provide support for any such cases. 34 | -- 35 | 36 | BSQ is stored in a Bitcoin wallet, but the Bisq software takes several measures to keep BSQ and BTC separate to prevent mixing the two by accident. On disk, BTC and BSQ wallets are stored in separate files. In the Bisq interface, BSQ wallets are prefixed with a 'B' to prevent users from mistakenly using BSQ as BTC. 37 | 38 | As an additional protection measure, Bisq wallets use a special BIP44 derivation path that other wallets won't understand. 39 | 40 | For user convenience, the built-in Bisq wallets for BTC and BSQ share the same seed. 41 | 42 | More details are in the <>. 43 | 44 | === BSQ Genesis Distribution 45 | 46 | As you may have noticed, the Bisq DAO did not launch with a supply of zero BSQ tokens. So where did the initial supply of BSQ tokens come from? 47 | 48 | In short, the initial supply of BSQ tokens was created to account for all the contributions to the Bisq project before the mainnet launch of the Bisq DAO. 49 | 50 | These contributions can be divided into 2 segments. 51 | 52 | 1. _Before October 2017_ 53 | + 54 | In the early days of the project, before Bisq tracked compensation requests and voting results, Bisq collected donations. In October 2017, as part of the implementation of the <> plan, it was decided that 2.5 BTC of all donations would be distributed back to these patrons as BSQ where each person would receive an amount proportional to their prior contributions. 55 | + 56 | 2. _After October 2017_ 57 | + 58 | In October 2017, the Phase Zero plan went into effect. Subsequent contributions to Bisq were https://github.com/bisq-network/compensation/issues[documented on GitHub^] and stakeholders voted to approve those contributions https://docs.google.com/spreadsheets/d/1xlXDswj3251BPCOcII-UyWlX7o7jMkfYBE-IZ5te5Ck[on this spreadsheet^]. 59 | 60 | The genesis BSQ distribution was the sum of both segments of past contributions. 61 | 62 | Ultimately, the genesis transaction issued https://explorer.bisq.network/tx.html?tx=4b5417ec5ab6112bedf539c3b4f5a806ed539542d8b717e1c4470aa3180edce5[3,657,480 BSQ to over 200 past contributors^]. You can see https://blockstream.info/tx/4b5417ec5ab6112bedf539c3b4f5a806ed539542d8b717e1c4470aa3180edce5[the corresponding Bitcoin transaction here^]. 63 | 64 | Addresses were confirmed over email, Slack, Twitter, and on these two GitHub threads: https://github.com/bisq-network/compensation/issues/260[one^], https://github.com/bisq-network/compensation/issues/263[two^]. 65 | 66 | == Bisq DAO 67 | 68 | === Technical Overview 69 | 70 | There are 2 key points to note about how the Bisq DAO works. 71 | 72 | 1. **Every DAO action is an on-chain Bitcoin transaction.** Every DAO action requires BSQ, and since BSQ is bitcoin, every DAO action is also recorded on the Bitcoin blockchain. As noted above, this does NOT mean you should try to form your own BSQ transactions. But it does mean that every action you take on the Bisq DAO is immortalized on the Bitcoin blockchain, publicly verifiable, and virtually impossible to reverse. 73 | 74 | 2. **Bitcoin provides transaction integrity, and Bisq's own P2P network provides storage.** DAO actions such as making proposals and voting include extra data such as text and links that don't belong on the Bitcoin blockchain. This extra data is stored on Bisq's own P2P network (literally, Bisq users' hard drives). A hash of that extra data is included in the `OP_RETURN` output of the corresponding Bitcoin transaction. Then, the Bitcoin transaction ID is added to the extra data and broadcast to peers on the Bisq network. 75 | 76 | You can visualize it like this: 77 | 78 | .How Bisq stores data 79 | image::bisq-dao-data-model.png[How Bisq stores data] 80 | 81 | Storing a hash of the extra data on the Bitcoin blockchain ensures any attempts to manipulate it will fail, since the hash of the manipulated data will change and then not match the hash recorded in the corresponding Bitcoin transaction. 82 | 83 | NOTE: There's a bit of a chicken-and-egg problem here, since the Bitcoin transaction ID can only be known after the Bitcoin transaction is made, and the hash of a data object can only be made once the Bitcoin transaction ID is known. To get around this, the data object is hashed with `null` in place of the Bitcoin transaction ID, and the Bitcoin transaction ID is added afterward. Later, when the integrity of the data object needs to be validated, the Bitcoin transaction ID is replaced with `null` before the data object is hashed. 84 | 85 | === Voting Cycle 86 | 87 | Voting cycles are timed to last about 1 month. Duration is measured in blocks, so actual times may vary. 88 | 89 | ==== Proposal Phase 90 | 91 | _3600 blocks, about 24 days_ 92 | 93 | During this time, Bisq stakeholders (contributors and traders) can make proposals. It is not possible to edit a proposal, but it is possible to remove a proposal and submit a corrected one (only during this phase). 94 | 95 | There is a small fee to make proposals to discourage spam. Fees for proposals that are removed are not reimbursed. 96 | 97 | Proposals requesting the issuance of new BSQ will also require a small amount of BTC to be included in the proposal transaction so there is BTC to 'color' into BSQ. The spec requires 100 satoshis per BSQ token, so a request for 1000 BSQ will require 1000 × 100 = 100,000 satoshis. 98 | 99 | Keep in mind that the actual BSQ you end up with will be net the proposal fee: if your request for 1000 BSQ is approved, and if the proposal fee is 2 BSQ, you will end up with 998 BSQ in your wallet. 100 | 101 | For compensation requests, please make sure you follow <>. 102 | 103 | If the proposal phase ends before you can make your proposal, simply wait and make your proposal in the next proposal phase. 104 | 105 | ===== Other Details 106 | 107 | As illustrated in the image above, proposal transactions are published on the Bitcoin network and proposal data objects are broadcast on the Bisq P2P network. The Bitcoin transaction includes a hash of the proposal data object. 108 | 109 | After the proposal phase is over, there is a break of 150 blocks (about 1 day) to review and discuss proposals before voting begins. 110 | 111 | ==== Blind Voting Phase 112 | 113 | _450 blocks, about 3 days_ 114 | 115 | You may approve, reject, or abstain from casting a vote on proposals. It is highly recommended that you only approve or reject proposals for which you can make a well-informed decision. 116 | 117 | It is not necessary to have made a proposal to be able to vote—any stakeholder (anyone with BSQ) can participate in voting. 118 | 119 | Once you have made your selections, you must specify a stake and publish your votes. 120 | 121 | Votes cannot be changed once they are published. 122 | 123 | ===== Voting Stake 124 | 125 | Your voting weight is determined by 2 factors: _reputation_ (how much BSQ you've earned), and _stake_ (how much of your owned BSQ you allot to your vote) that you specify in your vote transaction. 126 | 127 | _Reputation_ is the amount of BSQ earned by doing work for the Bisq network, independent of the amount of BSQ spent or sold. So if Alice earns 10,000 BSQ by working on Bisq, and she sells 8,000 BSQ for BTC to pay her bills, her reputation value remains 10,000 BSQ. Caveat: reputation decays over time. BSQ earned decays linearly over a period of 2 years as soon as it's earned. So the reputation value of Alice's 10,000 BSQ is 5,000 BSQ one year after she earns it, and zero two years later. 128 | 129 | Reputation cannot be specified when making a vote transaction—it's automatically calculated for the user from their past contributions. 130 | 131 | _Stake_ is the literal amount of BSQ specified for the vote transaction. This is BSQ you own that you would like to devote to your vote. The more BSQ you allot, the more weight your vote will hold. BSQ specified for stake is unspendable for the duration of the voting cycle. 132 | 133 | **Total voting weight is the sum of reputation value and specified stake.** 134 | 135 | BSQ earned is worth more than BSQ bought. The idea is that there is no better measure of good-will and dedication to the project than actually working on the project. The arrangement still allows people who buy into the project considerable influence, while hopefully minimizing the potential of whales with bad intentions from buying their way in and sabotaging the project. 136 | 137 | ===== Other Details 138 | 139 | Votes are published on the Bitcoin network and _encrypted_ vote data objects are broadcast on the Bisq P2P network (hence the term 'blind' vote). The Bitcoin transaction includes a hash of the vote data object. BSQ specified for voting stake is also specified in this transaction, and cannot be spent until the vote reveal transaction is published. 140 | 141 | Following the end of the blind voting phase, there is a break of 10 blocks to protect against reorgs. 142 | 143 | ==== Vote Reveal Phase 144 | 145 | _450 blocks, about 3 days_ 146 | 147 | No action is required of the user during this phase aside from having the Bisq software online at some point during the vote reveal phase so it can publish the vote reveal transaction. 148 | 149 | You will see a pop-up in the UI when the transaction has been published. 150 | 151 | ===== Other Details 152 | 153 | Only a Bitcoin transaction is made in this phase—no additional data is broadcast to the Bisq P2P network. 154 | 155 | This transaction includes 2 items: 156 | 157 | 1. the key to decrypt the votes cast in the blind voting phase 158 | 2. a hash of the list of voting data objects received by the Bisq node making the transaction (ordered by transaction ID; details <<#determining-consensus,below>>) 159 | 160 | One of the inputs to this transaction is the BSQ reserved for stake, so once this transaction is published, that BSQ becomes spendable again. 161 | 162 | If a user fails to make their vote reveal transaction, their vote is rendered invalid. 163 | 164 | Again, for protection against reorgs, there is a break of 10 blocks after this phase is over. 165 | 166 | ==== Vote Result Phase 167 | 168 | _10 blocks, about 100 minutes_ 169 | 170 | This phase is more of a trigger, so allotting 10 blocks is more for consistency than a hard requirement. 171 | 172 | In this phase, Bisq nodes calculate vote results from proposals, voting stake, and votes (which can now be decrypted from the vote reveal transactions). 173 | 174 | ===== Determining Consensus 175 | 176 | We can trust that all Bisq nodes will get the same data from the Bitcoin blockchain. However, we cannot be sure that all Bisq nodes have obtained all corresponding data from the Bisq P2P network. It is critical that any potential inconsistencies be handled before determining vote results, otherwise, vote results may differ. 177 | 178 | This is why each Bisq node includes a hash of the list of the voting data objects it has received in its vote reveal transaction. While a hash of vote data objects is recorded on the Bitcoin blockchain for integrity, it's not guaranteed that every _voting data object itself_ is actually delivered to every Bisq node. 179 | 180 | So, when calculating vote results, the majority hash from the vote reveal transactions (majority by voting stake) is considered to be the authoritative representation of votes for the whole network. Vote result calculations are based on this uniform determination, ensuring consensus across the network. 181 | 182 | NOTE: This majority hash must have at least 80% of the vote stake—otherwise the whole voting cycle is invalidated and all proposals are rejected. Such inconsistencies should be exceptional, as they would indicate a significant problem with P2P network stability. This 80% threshold is also a security measure, as only an attacker with at least 80% of the total stake in a voting cycle could succeed. 183 | 184 | == Note on Unexpected Situations 185 | 186 | Great care has been taken to make sure that there are no opportunities for the Bisq DAO to be exploited by scammers, hackers, or others with bad intentions. 187 | 188 | Much expertise and theory went into the Bisq DAO's conception, implementation was careful, and testing was thorough. The resulting software is the best expression of the intention of these collective efforts, but it may not be infallible. 189 | 190 | We say this to establish that Bisq DAO code is not law. It has clear intentions, and every effort will be made to fix unintended results. 191 | 192 | While we hope nothing will be catastrophic enough to require it, hard forks, confiscation, and new issuances are options to deal with extreme scenarios. BSQ trading and DAO operations can be halted through an alert message from the lead developer. Such messages may be ignored by users if they think the measure is being abused, but ignoring such messages in a situation where the measure _is_ justified may exclude the user from reimbursement in case of losses. 193 | 194 | == Improve this doc 195 | 196 | Find a typo or have other suggestions for improvement? Please https://github.com/bisq-network/bisq-docs/blob/master/{docname}{docfilesuffix}[edit this doc] or https://github.com/bisq-network/bisq-docs/issues/new?title=Improvement+suggestion+for+{docname}{docfilesuffix}[report an issue]. 197 | -------------------------------------------------------------------------------- /dao.adoc: -------------------------------------------------------------------------------- 1 | = All About the Bisq DAO 2 | :imagesdir: ./images 3 | :!figure-caption: 4 | 5 | Here we collect resources to help you learn more about the Bisq DAO, what it is, and how it works. 6 | 7 | == General Info 8 | 9 | ==== <> 10 | Plain language introduction to the Bisq DAO. 11 | 12 | ==== https://www.youtube.com/playlist?list=PLFH5SztL5cYPAXWFz-IMB4dBZ0MEZEG_e[Bisq DAO in Brief (videos)^] 13 | Quick, short video series on the Bisq DAO. Get up to speed with a handful of 3-4 minute videos. 14 | 15 | ==== https://www.youtube.com/playlist?list=PLFH5SztL5cYOLdYJj3nQ6-DekbjMTVhCS[Bisq DAO Basics (videos)^] 16 | A more thorough treatment of the DAO covering everything from the basics of bitcoin transactions and colored coins to the economic and technical roots of the BSQ token and how it powers the Bisq DAO. 17 | 18 | == User Guides 19 | 20 | ==== <> 21 | This doc shows you how to use BSQ to get lower trading fees while compensating Bisq contributors at the same time. 22 | 23 | ==== <> 24 | This doc shows you how to use the Bisq DAO to govern Bisq by walking you through the process of making a proposal and voting. 25 | 26 | ==== <> 27 | Contributed to the Bisq Network? Great (and thank you!). Here is how to request compensation for your work. 28 | 29 | == More Details 30 | 31 | ==== <> 32 | Practical details on using the DAO, along with a brief technical overview: read this to understand what happens behind the scenes as you use the DAO. 33 | 34 | ==== <> 35 | An overview of the philosophy behind Bisq, the Bisq DAO, why both were created, and how it planned to decentralize its own governance from the very beginning. 36 | 37 | ==== <> 38 | Technical details of (1) what BSQ tokens actually are, how they're created, and how they're destroyed and (2) the various functions of the Bisq DAO and how BSQ enables them. The document includes several example transactions so you can explicitly see the processes. 39 | 40 | == Still Curious? 41 | 42 | We're happy to help. Feel free to reach out on https://keybase.io/team/bisq[Keybase^], https://bisq.community[the forum^], or https://twitter.com/bisq_network[Twitter^]. 43 | -------------------------------------------------------------------------------- /dao/phase-zero/README.adoc: -------------------------------------------------------------------------------- 1 | Supporting assets for link:../phase-zero.adoc[]. 2 | -------------------------------------------------------------------------------- /dao/phase-zero/bsq-creation-destruction.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/dao/phase-zero/bsq-creation-destruction.png -------------------------------------------------------------------------------- /dao/phase-zero/bsq-distribution.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/dao/phase-zero/bsq-distribution.png -------------------------------------------------------------------------------- /dao/phase-zero/bsq-uses.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/dao/phase-zero/bsq-uses.png -------------------------------------------------------------------------------- /dao/phase-zero/limitations.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/dao/phase-zero/limitations.png -------------------------------------------------------------------------------- /dao/phase-zero/volume.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/dao/phase-zero/volume.png -------------------------------------------------------------------------------- /docinfo-footer.html: -------------------------------------------------------------------------------- 1 | 101 | -------------------------------------------------------------------------------- /exchange/howto/add-alternative-base-currency.adoc: -------------------------------------------------------------------------------- 1 | = How to add an alternative base currency 2 | :stylesdir: ../../css 3 | :docinfodir: ../../ 4 | 5 | == Introduction 6 | 7 | This document describes the process how to submit a request for adding an alternative base currency (we refer as Altcoin in that document) to be supported in Bisq. Adding an Altcoin does not mean any endorsement. For making decisions in case of politically controversial requests we use the Bisq DAO voting process. 8 | 9 | Altcoin support is restricted by the technical infrastructure Bisq is based on. Supporting Altcoins which don't have BitcoinJ support would result in a huge implementation effort and it is not considered to be feasible in the near future. Mid term we might move to a new model based on Bitcoin Core in SPV mode with RPC interface and then the requirement for BitcoinJ and Java will get lifted. 10 | 11 | 12 | == Prerequisites 13 | 14 | === Altcoin is already traded in Bisq 15 | 16 | The Altcoin needs to have been already added to Bisq. 17 | 18 | === Java 19 | 20 | The Altcoin needs to come with a Java implementation. 21 | 22 | === P2SH 23 | 24 | The Altcoin needs to support P2SH for MultiSig. 25 | 26 | === BitcoinJ 27 | 28 | Because Bisq is based on BitcoinJ the Altcoin needs to have an implementation of BitcoinJ. 29 | 30 | === Support of libdohj approach 31 | 32 | The support of BitcoinJ need to follow the link:https://github.com/bisq-network/libdohj[libdohj] approach (e.g. we don't want to ship an additional alternative BitcoinJ library). 33 | 34 | 35 | == Instructions 36 | 37 | === Step 1. Implementation of the libdohj and BicoinJ relevant code and integration into Bisq 38 | 39 | The PR needs to add all the required implementation and integration code for libdohj, BicoinJ and Bisq. 40 | 41 | === Step 2. Add all required parameters 42 | 43 | All the required parameters (fees, limits,...) need to be defined. 44 | 45 | === Step 3. Rebrand to custom brand for testing once ready for public deployment 46 | 47 | The Bisq brand must not be used in a public mainnet test phase. Re-brand the Bisq word mark and logo. 48 | 49 | === Step 4. Test and deploy and get community motivated for trading 50 | 51 | - The fork has to be tested and deployed. 52 | - In the test period the requester operates the seed nodes and sets up an arbitrator and communicates clearly to their users that the fork is not operated by Bisq. 53 | - The network for the test run must not conflict with the official Bisq network. 54 | - The fork need to be tested on mainnet for at least 2 months. 55 | - There have to be min. 20 trades been executed in that test period. 56 | 57 | 58 | === Step 5. Make a pull request 59 | 60 | Make a pull request in GitHub to the Bisq `master` branch. Submit your pull request from a topic branch in your fork, not from your fork's `master` branch. 61 | 62 | If the PR gets merged the seed node operators and arbitrators will be assigned according the Bisq DAO process (requires lock up BSQ tokens as bond). 63 | 64 | 65 | == Caveats 66 | 67 | === Controversial Altcoins may be put to a vote 68 | 69 | - Any BSQ token holder can request that a decision for supporting the new base currency in Bisq should be decided in the Bisq DAO voting process (the Bisq DAO will be executed in a manual manner as long the full DAO version is not implemented according to the DAO <<../../dao/phase-zero#,phase zero>> doc). 70 | - If such a request for voting is filed the PR will be delayed until the next voting period. Filing a request for voting is described in the DAO voting document (See <<../../dao/phase-zero#,phase zero>>). 71 | - If the voting has > 50% of votes and reaches the required quorum (at least 5% of total BSQ stake need to vote on it) the result will be used to accept or reject the Altcoin. Not reaching the quorum results in a rejection. 72 | - For requesting again an Altcoin which got rejected by voting it requires a clear statement about the changed circumstances. Objecting the political positions is not sufficient (e.g. Coin XXX is not a scamcoin because of ....). 73 | - Any BSQ Altcoin holder can also request a voting to remove an already supported base currency. 74 | 75 | 76 | === Inactive base currencies will be de-listed 77 | 78 | - At each new release we will check if already supported base currencies have been traded in the past 4 months. If this requirement is not met the base currency will be removed. The Bisq trade statistics are taken as reference. Removal of a not-traded base currency will not be announced beside in the release notes of the new release. 79 | - Adding the base currency again requires a statement about the changed circumstances (e.g. link to discussions where demand for the base currency is documented,...). 80 | 81 | === Getting a new base currency into production might take a bit 82 | 83 | Adding a new base currency will be part of the normal release cycle. 84 | -------------------------------------------------------------------------------- /exchange/howto/collectd.conf: -------------------------------------------------------------------------------- 1 | Hostname "" 2 | Interval 30 3 | 4 | LoadPlugin syslog 5 | 6 | LogLevel info 7 | 8 | 9 | LoadPlugin cpu 10 | LoadPlugin df 11 | LoadPlugin disk 12 | LoadPlugin fhcount 13 | LoadPlugin interface 14 | LoadPlugin java 15 | LoadPlugin load 16 | LoadPlugin memory 17 | LoadPlugin processes 18 | LoadPlugin swap 19 | LoadPlugin write_graphite 20 | 21 | 22 | ReportByCpu true 23 | ValuesPercentage true 24 | 25 | 26 | 27 | MountPoint "/" 28 | 29 | 30 | 31 | Disk "/[hs]da/" 32 | 33 | 34 | 35 | ValuesAbsolute false 36 | ValuesPercentage true 37 | 38 | 39 | 40 | Interface "eth0" 41 | 42 | 43 | 44 | JVMArg "-verbose:jni" 45 | JVMArg "-Djava.class.path=/usr/share/collectd/java/collectd-api.jar:/usr/share/collectd/java/generic-jmx.jar" 46 | 47 | LoadPlugin "org.collectd.java.GenericJMX" 48 | 49 | # Generic heap/nonheap memory usage. 50 | 51 | ObjectName "java.lang:type=Memory" 52 | #InstanceFrom "" 53 | InstancePrefix "memory" 54 | 55 | # Creates four values: committed, init, max, used 56 | 57 | Type "memory" 58 | #InstancePrefix "" 59 | #InstanceFrom "" 60 | Table true 61 | Attribute "HeapMemoryUsage" 62 | InstancePrefix "heap-" 63 | 64 | 65 | # Creates four values: committed, init, max, used 66 | 67 | Type "memory" 68 | #InstancePrefix "" 69 | #InstanceFrom "" 70 | Table true 71 | Attribute "NonHeapMemoryUsage" 72 | InstancePrefix "nonheap-" 73 | 74 | 75 | 76 | # Memory usage by memory pool. 77 | 78 | ObjectName "java.lang:type=MemoryPool,*" 79 | InstancePrefix "memory_pool-" 80 | InstanceFrom "name" 81 | 82 | 83 | Type "memory" 84 | #InstancePrefix "" 85 | #InstanceFrom "" 86 | Table true 87 | Attribute "Usage" 88 | 89 | 90 | 91 | 92 | ServiceURL "service:jmx:rmi:///jndi/rmi://localhost:6969/jmxrmi" 93 | Collect "memory_pool" 94 | Collect "memory" 95 | 96 | 97 | # See /usr/share/doc/collectd/examples/GenericJMX.conf 98 | # for an example config. 99 | 100 | 101 | 102 | # 103 | # ReportRelative true 104 | # 105 | 106 | # 107 | # ValuesAbsolute true 108 | # ValuesPercentage false 109 | # 110 | 111 | # 112 | # Process "name" 113 | # ProcessMatch "foobar" "/usr/bin/perl foobar\\.pl.*" 114 | # 115 | 116 | # 117 | # ReportByDevice false 118 | # ReportBytes true 119 | # 120 | 121 | 122 | 123 | Host "localhost" 124 | Port "2003" 125 | Protocol "tcp" 126 | ReconnectInterval 0 127 | LogSendErrors false 128 | Prefix "servers." 129 | StoreRates true 130 | AlwaysAppendDS false 131 | EscapeCharacter "_" 132 | SeparateInstances false 133 | PreserveSeparator false 134 | DropDuplicateFields false 135 | 136 | 137 | -------------------------------------------------------------------------------- /exchange/howto/images/asset-hierarchy.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/exchange/howto/images/asset-hierarchy.png -------------------------------------------------------------------------------- /exchange/howto/images/asset-listing-fee.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/exchange/howto/images/asset-listing-fee.png -------------------------------------------------------------------------------- /exchange/howto/manual-dispute-payout.adoc: -------------------------------------------------------------------------------- 1 | This document has moved <<../../manual-dispute-payout#, here>>. 2 | -------------------------------------------------------------------------------- /exchange/howto/run-price-relay-node.adoc: -------------------------------------------------------------------------------- 1 | = How to run a price relay node 2 | :stylesdir: ../../css 3 | :docinfodir: ../../ 4 | 5 | == Introduction 6 | 7 | Bisq price relay nodes are used for retrieving market prices from several crypto currency market price providers as well as an estimation for the recommended mining fee. 8 | 9 | The currently supported market price providers are: 10 | 11 | . link:https://bitcoinaverage.com/[Bitcoin Average] for BTC-Fiat prices 12 | . link:https://poloniex.com/[Poloniex] for BTC-Altcoin prices 13 | . link:https://coinmarketcap.com/[Coinmarketcap] for BTC-Altcoin prices which are not available at Poloniex 14 | 15 | The mining fee estimation is delivered by: 16 | 17 | . link:https://bitcoinfees.21.co/[21.co] 18 | 19 | _Please note that the fee estimation function might get separated in the future into its own node._ 20 | 21 | 22 | === Background 23 | 24 | There are several reasons why the Bisq application does not connect directly to those providers: 25 | 26 | . For Bitcoin Average, it requires a paid subscription. The API key cannot be shared in an open source project. The requirement that each user would request and pay for an API key would be a usability killer. 27 | 28 | . Most providers are using Cloud Flare which require interactive Captchas to connect over Tor. API calls are not possible therefore with Tor. We want to use Tor by default for all network connections. 29 | 30 | For those 2 reasons we changed in earlier updates to the model of operating a price relay node running as Tor hidden service which connects to the service providers in clear net mode and contains the API key for Bitcoin Average. 31 | 32 | The price relay carries an important security aspect: + 33 | If the trader is using a percentage based price in the offer the actual trade price will be calculated using the current market price taken from the market price providers. If a node would deliver wrong data it could lead to a wrong trade price. Both traders check the calculated price by themselves but if both are connected to the same malicious provider it would result in a wrong trade price. Connection is made randomly to one of the providers in the list. We have as well a check for the age of the price and if the price is older than 30 min. the market price will be ignored. If no price is available, percentage based offers cannot be taken. A monitor service checking all price relay nodes and comparing their values for outliers is an important feature we need to add soon. 34 | 35 | The price relay is a simple http server and has to be set up to be accessible as Tor hidden service. Additionally if the operator wants he can open it to clear net (at least one clear net node is useful for supporting the regtest-without-tor dev setup for receiving market prices). We don't recommend to advertise the node address to not get traffic from non-Bisq users. There is no authentication scheme for Bisq users which make the service vulnerable for abuse of DDoS attacks. An authentication scheme for a P2P/open source environment is a challenge on its own but considered important to get explored further. 36 | 37 | 38 | The user connects to one of the nodes randomly and if a node fails it tries the next in random node in the list. 39 | If the first node is not available it decreases usability for the user because price display at startup takes longer. 40 | But more critical is that if both nodes are offline percentage based offers cannot be used. Similar if a price node has connection issues with the providers the prices are outdated and likely invalid for other peers when the user engages in a trade. 41 | 42 | 43 | == Price relay node operators 44 | 45 | The price relay node addresses (onion address) are hard coded in the application but can be overruled if the user adds a price relay node address as program argument. Any user can run therefore their own price relay node and connect to it. Though they require an API key for Bitcoin Average (cost is 12.- or 35.- USD/month depending on plan). 46 | 47 | Some contributors of Bisq are running the default price relay nodes which are hard coded in the application. It requires to set up a bond in BSQ to get the privilege to run a default price relay node and it requires that a certain quality of service is met. The operator also needs to acquire an API key for Bitcoin Average. Currently we trust that all operators do their best to provide a reliable service without defining exactly the metrics for the quality of service. 48 | 49 | Contributors running a price relay node will file a compensation request each month and get paid a fixed amount of BSQ for it if node availability was as expected. 50 | 51 | A default price relay node can be blocked by a network message in case the node does not fulfill the required quality. 52 | 53 | 54 | === Duties of the price relay node operator 55 | 56 | The operator of a price relay node needs to be responsive in case of price relay node software updates as well to OS updates. If there are connectivity issues he needs to investigate and if required upgrade his server (RAM, CPU). Requirements are rather low, we recommend 1 GB of RAM for one price relay node. He should check the error logs occasionally. He has to have a professional level of operational security to operate the node. 57 | Operators need to subscribe to the Bisq Slack channel 'bisq-pricenode' and act if their node reports errors. 58 | 59 | 60 | == System requirements for hosting machine 61 | 62 | . 1 GB of RAM 63 | . 10 GB disk space (SSD) 64 | . 1 TB network traffic 65 | . UPS (uninterruptible power supply) 66 | . Uptime of > 99.9% 67 | 68 | 69 | == Setup instructions 70 | 71 | === Step 1. Setup Tor 72 | 73 | Install latest Tor binaries (at Debian Tor it got installed as user debian-tor). 74 | 75 | ==== Step 1.1. Edit torrc file. 76 | 77 | Go to `/etc/tor` and edit the `torrc` file 78 | 79 | ---- 80 | HiddenServiceDir /var/lib/tor/ 81 | HiddenServicePort 80 127.0.0.1:8080 82 | ---- 83 | 84 | Optionally you can edit the torsocks.conf. 85 | 86 | 87 | ==== Step 1.2. Create start script 88 | 89 | start_tor.sh: + 90 | ---- 91 | #!/bin/bash 92 | 93 | # sudo -u debian-tor 94 | nohup sudo -u debian-tor tor > /dev/null 2>errors_tor.log & 95 | ---- 96 | 97 | ==== Step 1.3. Start Tor 98 | 99 | Start tor: 100 | `sh start_tor.sh` 101 | 102 | Wait about 1 minute until the hidden service is published. You should see it in the logs, otherwise go to `/var/lib/tor/` and check if the hostname file is available there. 103 | 104 | 105 | ==== Step 1.4. Copy the onion address 106 | 107 | Once you see the onion address is published copy it and pass it to the developers so it can be added to the hard coded list of nodes (in class: `io.bisq.core.provider.ProvidersRepository`) or make a PR to that class. 108 | 109 | 110 | ==== Step 1.5. Backup private key for onion address 111 | 112 | Go to `/var/lib/tor` and backup the private key and the hostname file in a safe location. If your server would crash you can re-install the same price relay node with the private key. 113 | 114 | 115 | === Step 2. Set up price relay node: 116 | 117 | ==== Step 2.1. Check out Bisq and build it according to the link:https://github.com/bisq-network/exchange/blob/master/doc/build.md[build.md] file. 118 | 119 | _Note: We will soon separate the price relay to its own project._ 120 | 121 | ==== Step 2.2. Acquire an API key from Bitcoin Average 122 | 123 | ==== Step 2.3. Create 2 sh files for the price relay node: 124 | 125 | start_node.sh: + 126 | ---- 127 | nohup sh loop.sh & 128 | ---- 129 | 130 | loop.sh: + 131 | ---- 132 | #!/bin/bash 133 | while true 134 | do 135 | echo `date` "(Re)-starting node" 136 | java -Xmx1700m -jar provider.jar [bitcoinAveragePrivKey] [bitcoinAveragePubKey] > /dev/null 2>errors.log 137 | echo `date` "node terminated unexpectedly!!" 138 | sleep 3 139 | done 140 | ---- 141 | 142 | Replace [bitcoinAveragePrivKey] and [bitcoinAveragePubKey] with your API keys. 143 | 144 | ==== Step 2.4. Start the price relay node 145 | 146 | `sh start_node.sh` 147 | 148 | ==== Step 2.5. Test if the services are available via Tor hidden service in Tor browser 149 | 150 | http://YOUR_ONION_ADDRESS.onion/getFees + 151 | http://YOUR_ONION_ADDRESS.onion/getAllMarketPrices 152 | 153 | Optional: If you support clear net access, test it with your IP/domain. 154 | 155 | 156 | == Monitoring 157 | 158 | Seed nodes are monitored in the Bisq Slack channel 'bisq-monitor' and errors are sent to the 'bisq-pricenode' channel. Operators need to subscribe to the 'bisq-pricenode' channel and act if their node reports errors. 159 | 160 | 161 | == Bond 162 | 163 | We define a Bond of 2000 BSQ for the privilege to run a price relay node. In case of severe failures of service (malicious or carelessness) the bond would be confiscated (burned). 164 | 165 | 166 | == Payment 167 | 168 | For the service the contributor provides by running and maintaining a price relay node as well as a compensation for the server costs we define a payment of 50 BSQ per month. 169 | For the setup we define a payment of 200 BSQ. 170 | -------------------------------------------------------------------------------- /exchange/howto/run-seednode.adoc: -------------------------------------------------------------------------------- 1 | = How to run a seed node 2 | :stylesdir: ../../css 3 | :docinfodir: ../../ 4 | 5 | Bisq seed nodes serve as static gateways for Bisq clients to get connected to Bisq's dynamic P2P network. 6 | 7 | In this doc, you will find information about: 8 | 9 | - what a seed node is and how it works 10 | - the duties of a seed node operator 11 | - the benefits of being a seed node operator 12 | - how to get a seed node up and running 13 | - where to get in touch 14 | 15 | == What is a Bisq seed node 16 | 17 | Bisq uses a highly anonymous and dynamic P2P network for communications between Bisq clients. In order to get access to the network, the Bisq network features always-up Bisq clients with static addresses: seed nodes. They have 2 main tasks: 18 | 19 | . Deliver the peer addresses of other dynamic network peers 20 | 21 | . Deliver the initial P2P network data like open offers, mailbox messages and arbitrators 22 | 23 | . Deliver the initial DAO state 24 | 25 | Being the gateways to the Bisq P2P network, seed nodes are among the first nodes a Bisq client connects to on each startup. Therefore, 26 | 27 | - seed nodes face a heavy load and are therefore operated on servers offering a high level of reliability and better connectivity than a Bisq client for home use. 28 | - A bad seed node can have a substantial impact on the Bisq network. A Bisq user may encounter anything from a longer startup time of her Bisq client (which is inconvenient but not critical) to missing messages sent to her by a trading partner or arbitrator while her Bisq client has been offline (which can lead to disputes, failed trades, bad reputation and even blocking of the Bisq client). 29 | 30 | All in all, seed nodes play a vital role in the Bisq network. They allow users easy access to the Bisq network and therefore must be kept online and available at all times. Without the seed nodes, a new Bisq client would not find its way into the network, at least not without manual intervention. Bad seed nodes can make it harder for a new client to join the network. 31 | 32 | == Seed node operators 33 | 34 | Being a seed node operator brings along duties and benefits making it worthwhile. 35 | 36 | === Duties of the seed node operator 37 | 38 | The operator of a seed node needs to: 39 | 40 | - find yourself a deputy in case you are not available (travel, holiday, others, ...). Usually, one of the developers is there to help. Just inform them on your setup and all is good. 41 | - keep the server up and running, including patching and hardening the operating system 42 | - keep the seed node software up to date 43 | - keep an eye on Bisq's communication channels for updates, issues, countermeasures, etc (see <>) 44 | - keep an eye on the logs of the seed node and the operating system, and act if something shows up 45 | - if necessary, report and escalate (see <>) 46 | - set up a bond of 20000 BSQ (twenty-thousand BSQ) to get the privilege to run a seed node. In case of severe failure of service, the bond gets confiscated (burned). 47 | - create a monthly report https://github.com/bisq-network/roles/issues/15[here] 48 | 49 | === Compensation 50 | 51 | A seed node operator has the right to: 52 | 53 | - file a compensation request over 200 BSQ for setting up a seed node 54 | - file a monthly compensation request. We define 50 BSQ per month as an appropriate compensation per seed node per month. 55 | 56 | [NOTE] 57 | ==== 58 | With the advent of the DAO and the subsequent need of an additional 300GB of disk space for the Bitcoin full node, the numbers here are currently under discussion. Until new figures are decided on, state your expenses for running the server and add the 50 BSQ on top to get your sum for compensation. 59 | ==== 60 | 61 | == Getting in Touch 62 | 63 | Bisq uses Slack to communicate via chat. As a seed node operator, you are required to 64 | 65 | - subscribe to the Bisq Slack channel `bisq-seednode` and `bisq-monitor` 66 | - the `bisq-seednode` channel is the place where updates, issues, countermeasures, heads-ups, etc are discussed. If you encounter a problem with your seed node and cannot solve it by yourself, this is the place to report to (with a specific question, logs, etc). A developer will get back to you. 67 | - the `bisq-monitor` channel is the place where issues with seed nodes are reported, either manually or by our monitoring service. If your seed node is mentioned for having an issue, you are required to react. 68 | - please be responsive when addressed 69 | 70 | == System requirements for hosting machine 71 | 72 | - Min. 4 GB of RAM 73 | - 400 GB of disk space 74 | - 2 TB network traffic 75 | - Uptime of > 99.9% 76 | - > 10000 file handles available (check `ulimit -Sn`) 77 | 78 | And please try to stay away from cheap hosting providers! They tend to not care about QOS, the hardware is slow, they occasionally even turned a service off without warning - ask us how we know... 79 | 80 | ## Get a seed node up and running 81 | 82 | You can run your seed node in many ways. The guide you are currently reading applies to a (debian-based) unix system with systemd available. Furthermore, we assume that only one seed node is operated per host. Please be aware that the guide is only a guide and not a step-by-step copy-and-paste how-to, as we ignore for example the need for the occasional root access and file permissions, swap, general opsec, among other things. In case your host differs from our reference system, we are sure you can handle yourself. 83 | 84 | There are four pieces to the puzzle of successfully running a seed node: 85 | 86 | - a Bitcoin full node 87 | - the Bisq seednode itself and 88 | - system health reports 89 | 90 | and last but not least, the all-important firewall. 91 | 92 | === Firewall 93 | 94 | Although every port that is to be used only by localhost clients should be hardened by configuration and source code already, we recommend whitelisting stuff that is actually needed. Here is an example on how to configure iptables accordingly (the config drops any incoming connections except connection from localhost, SSH and responses.): 95 | 96 | iptables -P INPUT DROP && iptables -A INPUT -i lo -j ACCEPT && iptables -A INPUT -p tcp --dport 22 -j ACCEPT && iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT 97 | 98 | [NOTE] 99 | ==== 100 | Make sure you execute *all `iptables` commands at once*! Executing only the first one is going to kick you out of your ssh session and does not let you back in. 101 | ==== 102 | 103 | === Bitcoin Node 104 | 105 | Start by setting up a user for the bitcoin core stuff. 106 | 107 | useradd -r -m bitcoind 108 | cd /home/bitcoind 109 | 110 | Download the Bitcoin Core binaries https://bitcoin.org/en/download[here] to this directory, unpack it and, for updating convenience, create a symlink to the necessary binaries (so you only have to change the symlink on update): 111 | 112 | tar xzf bitcoin-0.18.0-x86_64-linux-gnu.tar.gz 113 | ln -s bitcoin-0.18.0/bin/bitcoind bitcoind 114 | ln -s bitcoin-0.18.0/bin/bitcoin-cli bitcoin-cli 115 | 116 | Create a systemd service file `bitcoind.service` in the systemd service path for your operating system (something like `/usr/lib/systemd/system/`) and adapt it to your needs. We recommend to create a user `bitcoind` for service hardening reasons. In the end, it should look like 117 | 118 | ---- 119 | [Unit] 120 | Description=Bitcoind 121 | After=network.target 122 | 123 | [Service] 124 | ExecStart=bitcoind -daemon \ 125 | -printtoconsole \ 126 | -nodebuglogfile \ 127 | -pid=/home/bitcoind/.bitcoin/bitcoind.pid 128 | ExecStop=/home/bitcoind/bitcoin-cli stop 129 | 130 | Type=forking 131 | PIDFile=/home/bitcoind/.bitcoin/bitcoind.pid 132 | Restart=on-failure 133 | 134 | User=bitcoind 135 | Group=bitcoind 136 | 137 | PrivateTmp=true 138 | ProtectSystem=full 139 | NoNewPrivileges=true 140 | PrivateDevices=true 141 | MemoryDenyWriteExecute=true 142 | 143 | [Install] 144 | WantedBy=multi-user.target 145 | ---- 146 | 147 | Create a file `/home/bitcoind/.bitcoin/bitcoin.conf` that contains 148 | 149 | ---- 150 | txindex=1 151 | listen=0 152 | rpcallowip=127.0.0.1 153 | rpcuser=YOUR_USER_NAME 154 | rpcpassword=YOUR_PW 155 | blocknotify=sh ~/.bitcoin/blocknotify.sh %s 156 | ---- 157 | 158 | and another file `/home/bitcoind/.bitcoin/blocknotify.sh` that contains 159 | 160 | #!/bin/sh 161 | echo $1 | nc -w 1 127.0.0.1 5120 162 | 163 | and make it executable (`chmod +x /home/bitcoind/.bitcoin/blocknotify.sh`). 164 | 165 | Finally, enable and start the service 166 | 167 | systemctl enable bitcoind.service 168 | systemctl start bitcoind.service 169 | 170 | and observe the logs 171 | 172 | journalctl --unit bitcoind --follow 173 | 174 | and check if everything works as expected. 175 | 176 | === Bisq Seed Node 177 | 178 | Start by getting OpenJDK 10 up and running. 179 | 180 | For getting the Bisq binaries, we recommend cloning the Bisq Git repository and compiling the code on your server. This way, you have precise control over what version you want to deploy. Furthermore, updating is very simple, just pull the changes, recompile and restart your service. 181 | 182 | Furthermore, we recommend creating a user `bisq` in group `bisq` for service hardening reasons and using the `bisq` user's home directory to: 183 | 184 | useradd -r -m bisq 185 | cd /home/bisq 186 | git clone git@github.com:bisq-network/bisq.git 187 | cd bisq 188 | ./gradlew build -x test 189 | 190 | Create a systemd service file `bisq-seednode.service` (or copy the one shipped with bisq `$bisqdir/seednode/bisq-seednode.service`) in the systemd service path for your operating system (something like `/usr/lib/systemd/system/`) and adapt it to your needs. 191 | 192 | In the end, your file should look something like 193 | 194 | ---- 195 | [Unit] 196 | Description=Bisq Seed Node 197 | After=network.target 198 | 199 | [Service] 200 | Environment="JAVA_OPTS=-Xms512M -Xmx2000M -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=6969 -Dcom.sun.management.jmxremote.rmi.port=6969 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false" 201 | ExecStart=/home/bisq/bisq/bisq-seednode --appName=bisq-seednode --nodePort=8000 --userDataDir=/home/bisq/ --maxConnections=30 --fullDaoNode=true --rpcUser=YOUR_USER_NAME --rpcPassword=YOUR_PW --rpcPort=8332 --rpcBlockNotificationPort=5120 202 | 203 | Restart=on-failure 204 | 205 | User=bisq 206 | Group=bisq 207 | 208 | PrivateTmp=true 209 | ProtectSystem=full 210 | NoNewPrivileges=true 211 | PrivateDevices=true 212 | MemoryDenyWriteExecute=true 213 | 214 | [Install] 215 | WantedBy=multi-user.target 216 | ---- 217 | 218 | Note that the jmxremote JVM arguments are later used for monitoring the service, the rpc arguments are there to get the seed node hooked to the bitcoin service. Make sure that the YOUR_USER_NAME and YOUR_PW placeholders match the configuration of <>. 219 | 220 | Enable and start the seed node by 221 | 222 | 223 | `systemctl daemon-reload` + 224 | `systemctl enable bisq-seednode.service` + 225 | `systemctl start bisq-seednode.service` 226 | 227 | Keep an eye on the logs and see if everything works as expected: 228 | 229 | `journalctl --unit bisq-seednode --follow` 230 | 231 | In case you are about to take over a seed node from someone else, you need to manually import their onion address and private key. 232 | 233 | In `/home/bisq/.local/share/bisq_seednode/btc_mainnet/tor/hiddenservice/`, replace the files 234 | 235 | hostname 236 | private_key 237 | 238 | with the ones you received from the former seed node operator. Restart your service 239 | 240 | `systemctl restart bisq-seednode.service` and again, observe the logs and make sure everything works as expected. 241 | 242 | Finally, we ask you to prepare for the worst. Go to `/home/bisq/.local/share/bisq-seednode/btc_mainnet/tor/hiddenservice/` and backup the files 243 | 244 | hostname 245 | private_key 246 | 247 | to a secure location. In case your server loses the original files during a crash, you can recover easily by following the steps for taking over a seed node. All other data like the `db` or the `keys` directory are not relevant for the seed node. 248 | 249 | 250 | === System health reports 251 | 252 | Since seed nodes are such a crucial part of the Bisq network, we require periodic health reports to our https://monitor.bisq.network[monitor]. Since the monitor only accepts plain TCP connections for incoming data, we have to accept a bit of overhead to keep the monitor from being flooded with unauthorized input. 253 | 254 | In order to successfully report to the monitor, we need to create a TCP reverse proxy local to your host that can authenticate to the monitor. For this guide, we go with nginx, if you prefer another reverse proxy, we are sure you can handle yourself. 255 | 256 | First of all, if you have not already, install nginx on your system. 257 | 258 | Then proceed to creating the SSL certificate that is later used to authenticate against the monitor: 259 | 260 | cd /etc/nginx 261 | openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/cert.key -out /etc/nginx/cert.crt 262 | 263 | Use `ON = bisq.network`, `OU = seednodes` and `CN = ` for certificate creation. The onion address can be found in the `hostname` file mentioned before. 264 | 265 | Configure the reverse proxy with clientssl enabled. You can simply append the snippet below to your `/etc/nginx/nginx.conf` file: 266 | 267 | ---- 268 | stream { 269 | log_format basic '$remote_addr [$time_local] ' 270 | '$protocol Status $status Sent $bytes_sent Received $bytes_received ' 271 | 'Time $session_time'; 272 | 273 | error_log syslog:server=unix:/dev/log; 274 | access_log syslog:server=unix:/dev/log basic; 275 | 276 | server { 277 | listen 2003; 278 | allow 127.0.0.1; 279 | deny all; 280 | proxy_pass monitor.bisq.network:2002; 281 | proxy_ssl on; 282 | 283 | proxy_ssl_certificate /etc/nginx/cert.crt; 284 | proxy_ssl_certificate_key /etc/nginx/cert.key; 285 | 286 | proxy_ssl_session_reuse on; 287 | } 288 | } 289 | ---- 290 | 291 | Start your nginx and observe the logs to see if everything works as expected: 292 | 293 | systemctl restart nginx 294 | journalctl --unit nginx --follow 295 | 296 | Once you are satisfied, proceed on installing https://collectd.org/[collectd] and use https://github.com/bisq-network/bisq-docs/blob/master/exchange/howto/collectd.conf[this^] collectd config to start from. Fill in the onion address of your seed node 297 | 298 | Hostname "" 299 | 300 | and adjust the interface, df, disk plugins so that they match your setup (and thus, report meaningful metrics). 301 | 302 | Start your collectd service and check the logs for any issues: 303 | 304 | systemctl restart collectd 305 | journalctl --unit collectd --follow 306 | 307 | Once you are satisfied, go ahead and report your client certificate (`/etc/nginx/cert.crt`) to the `bisq-seednode` channel (see <>). The monitoring team will then whitelist your host and you can enjoy your metrics at https://monitor.bisq.network. 308 | -------------------------------------------------------------------------------- /exchange/images/payment-protocol.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/exchange/images/payment-protocol.png -------------------------------------------------------------------------------- /exchange/images/trade-process-detail.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/exchange/images/trade-process-detail.png -------------------------------------------------------------------------------- /exchange/images/trade-process-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/exchange/images/trade-process-overview.png -------------------------------------------------------------------------------- /getting-started-dao-traders.adoc: -------------------------------------------------------------------------------- 1 | = User Guide: Bisq DAO for Traders 2 | :imagesdir: ./images 3 | :!figure-caption: 4 | 5 | This short guide will show you how to use BSQ to pay lower trading fees. Using BSQ also compensates Bisq's contributors, making the Bisq network a sustainable free software project. 6 | 7 | Bisq's token is a bit different from most other exchange tokens: its primary reason to exist is to enable the decentralized operation and management of the Bisq network. That means no central wallets or accounts to accumulate funds, and no legal entity or leadership team to control strategy. See more details <> or in https://www.youtube.com/playlist?list=PLFH5SztL5cYPAXWFz-IMB4dBZ0MEZEG_e[these videos^]. 8 | 9 | For you, as a trader, discounted trading fees are a practical result of this approach: the mechanisms above require that trading fees be paid in BSQ, so the software encourages traders to pay fees with BSQ by making them cheaper than plain BTC fees. 10 | 11 | Let's see how to take advantage of this. 12 | 13 | == Acquire BSQ 14 | 15 | Although BSQ is <>, it's colored bitcoin that must be kept in a Bisq wallet, separate from plain bitcoin. 16 | 17 | To help you do this, and to avoid mistakes, Bisq automatically generates a separate BSQ wallet for you with its own address prefixed with a 'B'—so you can be sure when you're sending or receiving from a BSQ address. 18 | 19 | === Get Your BSQ Address 20 | 21 | You can find your BSQ wallet address in `DAO` > `BSQ wallet` > `Receive`. 22 | 23 | .Where to find your BSQ wallet address. 24 | image::bsq-wallet-address.png[Where to find your BSQ wallet address.] 25 | 26 | === Create BSQ Payment Account 27 | 28 | To trade BSQ on Bisq, you need to set up an altcoin account using your BSQ address. 29 | 30 | [NOTE] 31 | .What is instant trading? 32 | ==== 33 | For altcoins, Bisq offers instant trading, which shortens the trade period to a _maximum_ of 1 hour. Everything else about instant trades is the same as non-instant trades. 34 | 35 | Instant offers are marked as `Altcoins Instant` in the order book, and you can only accept those offers with an instant altcoins account. Non-instant payment accounts can only be used for non-instant offers. 36 | ==== 37 | 38 | We're going to leave that box unchecked and make this one a regular non-instant account. 39 | 40 | .Set up BSQ payment account. 41 | image::add-new-bsq-account.png[Set up BSQ payment account.] 42 | 43 | === Make or Take a BSQ Offer 44 | 45 | Now that you have a BSQ payment account configured, you can trade BSQ. 46 | 47 | Simply pick an offer you like (or make an offer of your own) and complete the trade. 48 | 49 | .Pick a BSQ offer you like and make the trade. 50 | image::bsq-buy-offers.png[Pick a BSQ offer you like and make the trade.] 51 | 52 | == Use BSQ to Pay Trading Fees 53 | 54 | Once you've got some BSQ, you can use it to pay trading fees. 55 | 56 | When you get to the `Take offer` screen where you confirm the trade amount, you'll see a toggle for trading fees where you can select between BTC and BSQ trading fees. 57 | 58 | .Trading fee toggle. 59 | image::trading-fee-toggle.png[Trading fee toggle.] 60 | 61 | Pick the option you like better and complete the trade! 62 | 63 | == Beyond Trading Fees 64 | 65 | BSQ is also a core element of Bisq's governance mechanism, allowing stakeholders like you to have a hand in crafting the strategy of the project through a voting process. 66 | 67 | You can learn more about it in <> and https://www.youtube.com/playlist?list=PLFH5SztL5cYPAXWFz-IMB4dBZ0MEZEG_e[these videos^]. 68 | 69 | We've also written a <> that walks you through a DAO voting process. 70 | 71 | == Improve this doc 72 | 73 | Find a typo or have other suggestions for improvement? Please https://github.com/bisq-network/bisq-docs/blob/master/{docname}{docfilesuffix}[edit this doc] or https://github.com/bisq-network/bisq-docs/issues/new?title=Improvement+suggestion+for+{docname}{docfilesuffix}[report an issue]. 74 | -------------------------------------------------------------------------------- /getting-started-dao.adoc: -------------------------------------------------------------------------------- 1 | = User Guide: Bisq DAO for Contributors 2 | :imagesdir: ./images 3 | :!figure-caption: 4 | 5 | This guide will show you how to use the Bisq DAO's governance mechanism by walking you through the process of making a proposal and voting. 6 | 7 | Voting is a crucial duty in the Bisq DAO that makes decision-making for the Bisq project accessible to all who use it—users and contributors alike. You'll see how to make a proposal, vote on other proposals, and how the BSQ token enables the process to be handled in a decentralized and trustless but meritocratic way. 8 | 9 | For a brief overview of how the Bisq DAO works, see our <> doc. 10 | 11 | == Obtain BSQ 12 | 13 | BSQ is the unit of value that powers the Bisq DAO. You'll need a little bit of it to make a proposal and vote. 14 | 15 | NOTE: You can learn more about the BSQ token, how it's issued, and more in our <> and/or our <>. 16 | 17 | As of this writing, it costs 2 BSQ to make a proposal and 2 BSQ to cast a vote, but these fees are DAO parameters themselves that can be changed through DAO voting. 18 | 19 | One way to acquire BSQ is by <>. Otherwise, you can buy BSQ on the market just like you would buy any other altcoin on Bisq. 20 | 21 | Simply make or take an offer you like: 22 | 23 | .BSQ buy offers. 24 | image::bsq-buy-offers.png[BSQ buy offers] 25 | 26 | You'll only need 2 BSQ to make a proposal, but if you want to vote as well, you'll need at least 10 BSQ to get started. 27 | 28 | In either case, you'll also need a little bit of bitcoin in your Bisq wallet to pay for fees associated with the proposal and voting transactions (0.005 BTC should be more than sufficient). 29 | 30 | //See more details on how to buy BSQ in <>. 31 | 32 | == Participate in a voting cycle 33 | 34 | As we cover in our <> doc, the BSQ token has several functions within Bisq. 35 | 36 | Here, we will focus on governance: making proposals and voting on proposals to adjust various aspects of Bisq. 37 | 38 | We'll do this by participating in one voting cycle in the Bisq DAO. Voting cycles are composed of 4 phases and last for 4,680 blocks (about 1 month on average). 39 | 40 | Here are the 4 phases: 41 | 42 | 1. **Proposal phase**, in which stakeholders submit compensation requests and other proposals requesting reimbursements for trading fees, changes in trading parameters, or changes in some other aspect of the Bisq project. After the proposal phase is over, there is a break of 150 blocks (about 1 day) to review and discuss proposals before voting begins. 43 | 2. **Blind voting phase**, in which stakeholders cast their votes on submitted proposals. Votes are encrypted in this phase to prevent later voters from being influenced by earlier voters. Following the end of the blind voting phase, there is a break of 10 blocks to protect against reorgs. 44 | 3. **Vote reveal phase**, in which each stakeholder sends the decryption key for their vote. Again, for protection against reorgs, there is a break of 10 blocks after this phase is over. 45 | 4. **Vote result phase**, in which vote results are calculated and BSQ is issued accordingly. 46 | 47 | You can see approximate start and end dates for the current voting cycle on the `Dashboard` section of the `Governance` tab on the `DAO` screen. 48 | 49 | .Voting cycle overview. 50 | image::voting-cycle-overview.png[Voting cycle overview] 51 | 52 | Let's begin by making a proposal. 53 | 54 | === 1. Make a proposal 55 | 56 | NOTE: Proposals can only be made during the proposal phase. If the voting cycle is in any other phase, you'll need to wait for the proposal phase of the next voting cycle to make your proposal. 57 | 58 | In the `Make proposal` section of the `Governance` tab of the `DAO` screen, you'll find the form to make a new proposal. Pick the type of proposal you want to make from the dropdown, fill the form, and hit `Make proposal`. 59 | 60 | IMPORTANT: Make sure your proposal is well-considered and fits conventions and expectations, which you can read about <>. It may also help to take a look at https://github.com/bisq-network/proposals/issues[past proposals^] to see how they were made and discussed. 61 | 62 | We'll make a general proposal here, for demonstration: 63 | 64 | .Make a proposal. 65 | image::make-dao-proposal.png[Make a proposal] 66 | 67 | If you made a contribution to Bisq, you'll make your request for compensation in the form of a proposal—the proposal type will be `Compensation request`. See guidelines for those requests <>. 68 | 69 | When you're done, you can sit back and relax until voting starts. 70 | 71 | === 2a. Vote on proposals 72 | 73 | [.float-group] 74 | -- 75 | [.right.text-center] 76 | .Cast vote on proposals. 77 | image::vote-proposal.png[Cast vote on proposals,400,400] 78 | 79 | Once the period to make proposals is over, it's time to vote. 80 | 81 | You can see all proposals in the current voting cycle in the `Browse open proposals` section of the `Governance` tab on the `DAO` screen. 82 | 83 | Click through each proposal to see more details, and then vote—it's strongly recommended that you only accept or reject proposals you know well and have a strong opinion about. 84 | 85 | -- 86 | 87 | === 2b. Submit votes 88 | 89 | When you're done selecting your votes, don't forget to actually submit your votes! It can be easy to miss this. 90 | 91 | [.float-group] 92 | -- 93 | [.left.text-center] 94 | .Select voting weight and submit all votes. 95 | image::vote-submit.png[Select voting weight and submit all votes,400,400] 96 | 97 | To submit your votes, you need to specify a BSQ amount to use for **voting stake**. The more BSQ you stake for your vote, the more weight it will carry. This BSQ cannot be traded or otherwise transferred until your vote reveal transaction is published. 98 | 99 | The software has checks to prevent such BSQ from being spent, but if BSQ staked for voting is somehow spent, the corresponding vote will be rendered invalid. 100 | 101 | This is why, as you see in the screenshot to the left, we use most (but not all) of our BSQ for the voting stake—we left some BSQ available for spending in case we need it for other purposes during the remainder of the voting cycle. 102 | 103 | -- 104 | 105 | `Vote weight from earned BSQ` is BSQ earned from contributing to Bisq: this BSQ is treated slightly differently from BSQ bought on the open market when determining a stakeholder's voting weight. 106 | 107 | NOTE: For more details on how voting weight is determined, see <> of our User Reference doc. 108 | 109 | Once you've entered a voting stake, go ahead and click the `Vote on all proposals` button at the bottom of the screen. 110 | 111 | === 3. Reveal your vote 112 | 113 | [.float-group] 114 | -- 115 | 116 | After the blind voting phase is over, **you must make sure Bisq goes back online at some point during the vote reveal phase to publish your vote reveal transaction**. 117 | 118 | [.right.text-center] 119 | .Vote reveal pop-up. 120 | image::vote-reveal-popup.png[Vote reveal pop-up.,400,400] 121 | 122 | Bisq will publish the transaction automatically when it's online, so you don't have to actually do anything, and you'll see a pop-up when the transaction is published. 123 | 124 | This transaction includes the key to decrypt your vote from the blind voting phase. It also includes a representation of all votes you've received from the network, which is used to determine a consensus of all votes cast on the network. See more details <>. 125 | 126 | Don't forget this step! If your vote reveal transaction is not published, your vote cannot be decrypted, and so it cannot be counted. 127 | 128 | -- 129 | 130 | === 4. Get vote results 131 | 132 | Once the vote reveal phase is over, results are calculated and the next voting cycle starts. 133 | 134 | You can see results of the last voting cycle in the `Vote results` section of the `Governance` tab of the `DAO` screen. 135 | 136 | .See voting results. 137 | image::dao-vote-results.png[See voting results.] 138 | 139 | If your proposal was a compensation request, this is when the BTC you included in your request will show as BSQ (after having been 'colored' by the voting process). Check your BSQ wallet balance in the `BSQ Wallet` tab of the `DAO` screen to see the updated balance. 140 | 141 | That's it—you've now participated in a full voting cycle of the Bisq DAO, the decentralized governance mechanism for the Bisq exchange. 142 | 143 | Bravo! 144 | 145 | == Explore a BSQ block explorer 146 | 147 | Since BSQ is just bitcoin, you can see BSQ transactions on any bitcoin block explorer. But because these bitcoins are colored in a way that only Bisq understands, ordinary bitcoin block explorers can't recognize which bitcoin transactions are also BSQ transactions. 148 | 149 | So there's a https://explorer.bisq.network/[BSQ block explorer^]. Whenever you do a BSQ transaction, you can see it there. 150 | 151 | Here's a screenshot of the past few BSQ transactions as of the end of April 2019, just a few days after the BSQ genesis transaction. 152 | 153 | You'll notice that this block explorer recognizes the various transaction properties that make valid BSQ transactions, and it labels them accordingly. 154 | 155 | Here's a snapshot of the latest transactions on the BSQ explorer during a voting phase: 156 | 157 | .Some BSQ transactions on the https://explorer.bisq.network[BSQ block explorer^]. 158 | image::bsq-block-explorer-voting.png[Some recent BSQ transactions] 159 | 160 | Typically, most transactions will be for transfers and paying trade fees—governance-related BSQ transactions for voting and vote reveals will only occur during the times of their respective phases. Proposals can be made at any time during the proposal phase, but tend to be made toward the end of the phase. 161 | 162 | == Next steps 163 | 164 | We covered the Bisq DAO here in a very practical way: just the steps you need to follow to make a proposal and vote. 165 | 166 | To keep this guide as simple as possible, we left out most details of what's happening under the hood. For those details, you might be interested in checking out our <> and <>. 167 | 168 | For more conceptual details, be sure to check out our <> doc and https://www.youtube.com/playlist?list=PLFH5SztL5cYPAXWFz-IMB4dBZ0MEZEG_e[Bisq DAO in Brief^] video series. 169 | 170 | == Get help and stay in touch 171 | 172 | If you get stuck, reach out! There's a community of people to help you on https://keybase.io/team/bisq[Keybase^], the https://bisq.community/[Bisq forum^], and the https://www.reddit.com/r/bisq/[/r/bisq subreddit^]. 173 | 174 | You can get news and updates about Bisq via https://twitter.com/bisq_network[Twitter^] and https://www.youtube.com/c/bisq-network[YouTube^]. 175 | 176 | And if you really like Bisq, <>! Even if you're not a developer, there's much you can do. 177 | 178 | == Improve this doc 179 | 180 | Find a typo or have other suggestions for improvement? Please https://github.com/bisq-network/bisq-docs/blob/master/{docname}{docfilesuffix}[edit this doc] or https://github.com/bisq-network/bisq-docs/issues/new?title=Improvement+suggestion+for+{docname}{docfilesuffix}[report an issue]. 181 | -------------------------------------------------------------------------------- /gradle/wrapper/gradle-wrapper.jar: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/gradle/wrapper/gradle-wrapper.jar -------------------------------------------------------------------------------- /gradle/wrapper/gradle-wrapper.properties: -------------------------------------------------------------------------------- 1 | distributionBase=GRADLE_USER_HOME 2 | distributionPath=wrapper/dists 3 | distributionUrl=https\://services.gradle.org/distributions/gradle-5.6.4-all.zip 4 | zipStoreBase=GRADLE_USER_HOME 5 | zipStorePath=wrapper/dists 6 | -------------------------------------------------------------------------------- /gradlew: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env sh 2 | 3 | ############################################################################## 4 | ## 5 | ## Gradle start up script for UN*X 6 | ## 7 | ############################################################################## 8 | 9 | # Attempt to set APP_HOME 10 | # Resolve links: $0 may be a link 11 | PRG="$0" 12 | # Need this for relative symlinks. 13 | while [ -h "$PRG" ] ; do 14 | ls=`ls -ld "$PRG"` 15 | link=`expr "$ls" : '.*-> \(.*\)$'` 16 | if expr "$link" : '/.*' > /dev/null; then 17 | PRG="$link" 18 | else 19 | PRG=`dirname "$PRG"`"/$link" 20 | fi 21 | done 22 | SAVED="`pwd`" 23 | cd "`dirname \"$PRG\"`/" >/dev/null 24 | APP_HOME="`pwd -P`" 25 | cd "$SAVED" >/dev/null 26 | 27 | APP_NAME="Gradle" 28 | APP_BASE_NAME=`basename "$0"` 29 | 30 | # Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. 31 | DEFAULT_JVM_OPTS="" 32 | 33 | # Use the maximum available, or set MAX_FD != -1 to use that value. 34 | MAX_FD="maximum" 35 | 36 | warn () { 37 | echo "$*" 38 | } 39 | 40 | die () { 41 | echo 42 | echo "$*" 43 | echo 44 | exit 1 45 | } 46 | 47 | # OS specific support (must be 'true' or 'false'). 48 | cygwin=false 49 | msys=false 50 | darwin=false 51 | nonstop=false 52 | case "`uname`" in 53 | CYGWIN* ) 54 | cygwin=true 55 | ;; 56 | Darwin* ) 57 | darwin=true 58 | ;; 59 | MINGW* ) 60 | msys=true 61 | ;; 62 | NONSTOP* ) 63 | nonstop=true 64 | ;; 65 | esac 66 | 67 | CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar 68 | 69 | # Determine the Java command to use to start the JVM. 70 | if [ -n "$JAVA_HOME" ] ; then 71 | if [ -x "$JAVA_HOME/jre/sh/java" ] ; then 72 | # IBM's JDK on AIX uses strange locations for the executables 73 | JAVACMD="$JAVA_HOME/jre/sh/java" 74 | else 75 | JAVACMD="$JAVA_HOME/bin/java" 76 | fi 77 | if [ ! -x "$JAVACMD" ] ; then 78 | die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME 79 | 80 | Please set the JAVA_HOME variable in your environment to match the 81 | location of your Java installation." 82 | fi 83 | else 84 | JAVACMD="java" 85 | which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 86 | 87 | Please set the JAVA_HOME variable in your environment to match the 88 | location of your Java installation." 89 | fi 90 | 91 | # Increase the maximum file descriptors if we can. 92 | if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then 93 | MAX_FD_LIMIT=`ulimit -H -n` 94 | if [ $? -eq 0 ] ; then 95 | if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then 96 | MAX_FD="$MAX_FD_LIMIT" 97 | fi 98 | ulimit -n $MAX_FD 99 | if [ $? -ne 0 ] ; then 100 | warn "Could not set maximum file descriptor limit: $MAX_FD" 101 | fi 102 | else 103 | warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT" 104 | fi 105 | fi 106 | 107 | # For Darwin, add options to specify how the application appears in the dock 108 | if $darwin; then 109 | GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\"" 110 | fi 111 | 112 | # For Cygwin, switch paths to Windows format before running java 113 | if $cygwin ; then 114 | APP_HOME=`cygpath --path --mixed "$APP_HOME"` 115 | CLASSPATH=`cygpath --path --mixed "$CLASSPATH"` 116 | JAVACMD=`cygpath --unix "$JAVACMD"` 117 | 118 | # We build the pattern for arguments to be converted via cygpath 119 | ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null` 120 | SEP="" 121 | for dir in $ROOTDIRSRAW ; do 122 | ROOTDIRS="$ROOTDIRS$SEP$dir" 123 | SEP="|" 124 | done 125 | OURCYGPATTERN="(^($ROOTDIRS))" 126 | # Add a user-defined pattern to the cygpath arguments 127 | if [ "$GRADLE_CYGPATTERN" != "" ] ; then 128 | OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)" 129 | fi 130 | # Now convert the arguments - kludge to limit ourselves to /bin/sh 131 | i=0 132 | for arg in "$@" ; do 133 | CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -` 134 | CHECK2=`echo "$arg"|egrep -c "^-"` ### Determine if an option 135 | 136 | if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then ### Added a condition 137 | eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"` 138 | else 139 | eval `echo args$i`="\"$arg\"" 140 | fi 141 | i=$((i+1)) 142 | done 143 | case $i in 144 | (0) set -- ;; 145 | (1) set -- "$args0" ;; 146 | (2) set -- "$args0" "$args1" ;; 147 | (3) set -- "$args0" "$args1" "$args2" ;; 148 | (4) set -- "$args0" "$args1" "$args2" "$args3" ;; 149 | (5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;; 150 | (6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;; 151 | (7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;; 152 | (8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;; 153 | (9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;; 154 | esac 155 | fi 156 | 157 | # Escape application args 158 | save () { 159 | for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done 160 | echo " " 161 | } 162 | APP_ARGS=$(save "$@") 163 | 164 | # Collect all arguments for the java command, following the shell quoting and substitution rules 165 | eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS" 166 | 167 | # by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong 168 | if [ "$(uname)" = "Darwin" ] && [ "$HOME" = "$PWD" ]; then 169 | cd "$(dirname "$0")" 170 | fi 171 | 172 | exec "$JAVACMD" "$@" 173 | -------------------------------------------------------------------------------- /gradlew.bat: -------------------------------------------------------------------------------- 1 | @if "%DEBUG%" == "" @echo off 2 | @rem ########################################################################## 3 | @rem 4 | @rem Gradle startup script for Windows 5 | @rem 6 | @rem ########################################################################## 7 | 8 | @rem Set local scope for the variables with windows NT shell 9 | if "%OS%"=="Windows_NT" setlocal 10 | 11 | set DIRNAME=%~dp0 12 | if "%DIRNAME%" == "" set DIRNAME=. 13 | set APP_BASE_NAME=%~n0 14 | set APP_HOME=%DIRNAME% 15 | 16 | @rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. 17 | set DEFAULT_JVM_OPTS= 18 | 19 | @rem Find java.exe 20 | if defined JAVA_HOME goto findJavaFromJavaHome 21 | 22 | set JAVA_EXE=java.exe 23 | %JAVA_EXE% -version >NUL 2>&1 24 | if "%ERRORLEVEL%" == "0" goto init 25 | 26 | echo. 27 | echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 28 | echo. 29 | echo Please set the JAVA_HOME variable in your environment to match the 30 | echo location of your Java installation. 31 | 32 | goto fail 33 | 34 | :findJavaFromJavaHome 35 | set JAVA_HOME=%JAVA_HOME:"=% 36 | set JAVA_EXE=%JAVA_HOME%/bin/java.exe 37 | 38 | if exist "%JAVA_EXE%" goto init 39 | 40 | echo. 41 | echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 42 | echo. 43 | echo Please set the JAVA_HOME variable in your environment to match the 44 | echo location of your Java installation. 45 | 46 | goto fail 47 | 48 | :init 49 | @rem Get command-line arguments, handling Windows variants 50 | 51 | if not "%OS%" == "Windows_NT" goto win9xME_args 52 | 53 | :win9xME_args 54 | @rem Slurp the command line arguments. 55 | set CMD_LINE_ARGS= 56 | set _SKIP=2 57 | 58 | :win9xME_args_slurp 59 | if "x%~1" == "x" goto execute 60 | 61 | set CMD_LINE_ARGS=%* 62 | 63 | :execute 64 | @rem Setup the command line 65 | 66 | set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar 67 | 68 | @rem Execute Gradle 69 | "%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS% 70 | 71 | :end 72 | @rem End local scope for the variables with windows NT shell 73 | if "%ERRORLEVEL%"=="0" goto mainEnd 74 | 75 | :fail 76 | rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of 77 | rem the _cmd.exe /c_ return code! 78 | if not "" == "%GRADLE_EXIT_CONSOLE%" exit 1 79 | exit /b 1 80 | 81 | :mainEnd 82 | if "%OS%"=="Windows_NT" endlocal 83 | 84 | :omega 85 | -------------------------------------------------------------------------------- /images/account-signing-details-pop.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/account-signing-details-pop.png -------------------------------------------------------------------------------- /images/account-signing-limit-details.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/account-signing-limit-details.png -------------------------------------------------------------------------------- /images/add-new-bsq-account.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/add-new-bsq-account.png -------------------------------------------------------------------------------- /images/after-adding-fiat-account.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/after-adding-fiat-account.png -------------------------------------------------------------------------------- /images/altcoins-instant.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/altcoins-instant.png -------------------------------------------------------------------------------- /images/before-adding-fiat-account.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/before-adding-fiat-account.png -------------------------------------------------------------------------------- /images/bisq-dao-data-model.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/bisq-dao-data-model.png -------------------------------------------------------------------------------- /images/bisq-docs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/bisq-docs.png -------------------------------------------------------------------------------- /images/bsq-block-explorer-trading.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/bsq-block-explorer-trading.png -------------------------------------------------------------------------------- /images/bsq-block-explorer-voting.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/bsq-block-explorer-voting.png -------------------------------------------------------------------------------- /images/bsq-buy-offers.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/bsq-buy-offers.png -------------------------------------------------------------------------------- /images/bsq-wallet-address.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/bsq-wallet-address.png -------------------------------------------------------------------------------- /images/buyer-seller-address.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/buyer-seller-address.png -------------------------------------------------------------------------------- /images/check-dao-timing.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/check-dao-timing.png -------------------------------------------------------------------------------- /images/closing-message.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/closing-message.png -------------------------------------------------------------------------------- /images/complete-trade.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/complete-trade.png -------------------------------------------------------------------------------- /images/configure-fiat-account.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/configure-fiat-account.png -------------------------------------------------------------------------------- /images/configure-offer-alert.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/configure-offer-alert.png -------------------------------------------------------------------------------- /images/configure-price-alert.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/configure-price-alert.png -------------------------------------------------------------------------------- /images/confirm-deal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/confirm-deal.png -------------------------------------------------------------------------------- /images/dao-vote-results.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/dao-vote-results.png -------------------------------------------------------------------------------- /images/dao-voting.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/dao-voting.png -------------------------------------------------------------------------------- /images/deposit-details.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/deposit-details.png -------------------------------------------------------------------------------- /images/determine-winner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/determine-winner.png -------------------------------------------------------------------------------- /images/engage-arbitrator-v116.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/engage-arbitrator-v116.png -------------------------------------------------------------------------------- /images/external-link-ltr-icon-grey.svg: -------------------------------------------------------------------------------- 1 | 2 | 16 | 18 | 19 | 21 | image/svg+xml 22 | 24 | 25 | 26 | 27 | 29 | 49 | 55 | 60 | 64 | 65 | -------------------------------------------------------------------------------- /images/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/favicon.ico -------------------------------------------------------------------------------- /images/fund-bisq-wallet.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/fund-bisq-wallet.png -------------------------------------------------------------------------------- /images/get-bsq-address-094.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/get-bsq-address-094.png -------------------------------------------------------------------------------- /images/get-pubkey-hex.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/get-pubkey-hex.png -------------------------------------------------------------------------------- /images/include-private-keys.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/include-private-keys.png -------------------------------------------------------------------------------- /images/make-compensation-request.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/make-compensation-request.png -------------------------------------------------------------------------------- /images/make-dao-proposal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/make-dao-proposal.png -------------------------------------------------------------------------------- /images/mark-payment-sent.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/mark-payment-sent.png -------------------------------------------------------------------------------- /images/market-screen.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/market-screen.png -------------------------------------------------------------------------------- /images/mobile-notifications-architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/mobile-notifications-architecture.png -------------------------------------------------------------------------------- /images/mobile-notifications-setup.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/mobile-notifications-setup.png -------------------------------------------------------------------------------- /images/multisig-payout-tool.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/multisig-payout-tool.png -------------------------------------------------------------------------------- /images/p2sh-multisig-output-script.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/p2sh-multisig-output-script.png -------------------------------------------------------------------------------- /images/password-active.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/password-active.png -------------------------------------------------------------------------------- /images/password-removed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/password-removed.png -------------------------------------------------------------------------------- /images/peer-can-sign-offer-listing.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/peer-can-sign-offer-listing.png -------------------------------------------------------------------------------- /images/quick-link-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/quick-link-1.png -------------------------------------------------------------------------------- /images/quick-link-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/quick-link-2.png -------------------------------------------------------------------------------- /images/quick-link-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/quick-link-3.png -------------------------------------------------------------------------------- /images/quick-link-4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/quick-link-4.png -------------------------------------------------------------------------------- /images/remaining-time-to-pay.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/remaining-time-to-pay.png -------------------------------------------------------------------------------- /images/repeat-trading-peer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/repeat-trading-peer.png -------------------------------------------------------------------------------- /images/seed-words.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/seed-words.png -------------------------------------------------------------------------------- /images/select-an-offer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/select-an-offer.png -------------------------------------------------------------------------------- /images/seller-payment-details.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/seller-payment-details.png -------------------------------------------------------------------------------- /images/set-password.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/set-password.png -------------------------------------------------------------------------------- /images/start-mediation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/start-mediation.png -------------------------------------------------------------------------------- /images/start-trader-chat.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/start-trader-chat.png -------------------------------------------------------------------------------- /images/trading-fee-toggle-focused.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/trading-fee-toggle-focused.png -------------------------------------------------------------------------------- /images/trading-fee-toggle.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/trading-fee-toggle.png -------------------------------------------------------------------------------- /images/user-dao-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/user-dao-diagram.png -------------------------------------------------------------------------------- /images/vote-proposal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/vote-proposal.png -------------------------------------------------------------------------------- /images/vote-reveal-popup.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/vote-reveal-popup.png -------------------------------------------------------------------------------- /images/vote-submit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/vote-submit.png -------------------------------------------------------------------------------- /images/voting-cycle-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/voting-cycle-overview.png -------------------------------------------------------------------------------- /images/wallet-data.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bisq-network/bisq-docs/c3dc52fa62aa2bdfb5162cb6d7b147dcdc916055/images/wallet-data.png -------------------------------------------------------------------------------- /index.adoc: -------------------------------------------------------------------------------- 1 | = Bisq Network Documentation 2 | :imagesdir: ./images 3 | 4 | [NOTE] 5 | .These docs are migrating to https://bisq.wiki. 6 | ==== 7 | Many links below redirect to the wiki site, and those that don't will be moved soon. 8 | ==== 9 | 10 | == User Docs 11 | 12 | === Essentials: Trading on Bisq 13 | 14 | * https://bisq.wiki/Introduction[Introduction^] image:external-link-ltr-icon-grey.svg[external-link,13,13] — _Learn what Bisq is, why it exists and how it works_ 15 | * https://bisq.network/getting-started[Getting Started^] image:external-link-ltr-icon-grey.svg[external-link,13,13] — _Download, set up and start trading with Bisq in minutes_ 16 | * https://bisq.wiki/Wallet[Wallet Info^] image:external-link-ltr-icon-grey.svg[external-link,13,13] and https://bisq.wiki/Encrypting_your_wallet[Security^] image:external-link-ltr-icon-grey.svg[external-link,13,13] — _Set a password and save your seed words to keep your bitcoin safe_ 17 | * https://bisq.wiki/Backing_up_application_data[Backup^] image:external-link-ltr-icon-grey.svg[external-link,13,13] and https://bisq.wiki/Restoring_application_data[Recovery^] image:external-link-ltr-icon-grey.svg[external-link,13,13] — _Maintain backups to keep your settings and history safe_ 18 | * Staying Private — _Maximize control over your personal info and trading data_ 19 | * https://bisq.wiki/Trading_rules[Trading Rules^] image:external-link-ltr-icon-grey.svg[external-link,13,13] and https://bisq.wiki/Dispute_resolution[Dispute Resolution^] image:external-link-ltr-icon-grey.svg[external-link,13,13] — _Know what's expected of you and others when trading_ 20 | * https://bisq.wiki/Trading_fees[Fees^] image:external-link-ltr-icon-grey.svg[external-link,13,13] and Security Deposits — _Understand how your bitcoin is used and kept safe when trading_ 21 | * Support — _Get help from other Bisq users and contributors_ 22 | * https://bisq.wiki/Payment_methods[Payment Methods^] image:external-link-ltr-icon-grey.svg[external-link,13,13] — _Details on supported fiat currency payment methods and limitations_ 23 | * Altcoins — _Explore https://bisq.network/markets/[100+] supported cryptocurrencies, tokens and assets_ 24 | 25 | === Bisq DAO: Governing Bisq 26 | * <> — _Learn how the DAO enables Bisq's decentralized governance model_ 27 | * <> — _Use BSQ to get lower trading fees and compensate contributors_ 28 | * <> — _Govern Bisq through the DAO by making proposals and voting_ 29 | * <> — _Practical details on using the DAO, along with a brief technical overview_ 30 | * <> — _Technical details of DAO functions and transactions_ 31 | 32 | === Ecosystem 33 | 34 | * News and Announcements — _Stay informed with the Bisq https://github.com/bisq-network/proposals/issues/20[mailing list], https://twitter.com/bisq_network[Twitter], https://www.youtube.com/c/bisq-network[YouTube], https://www.facebook.com/bisqnetwork/[Facebook], etc_ 35 | * Media and Press — _Catch up on https://twitter.com/bisq_network/status/946723541298360320[talks, interviews, podcasts and articles] about Bisq_ 36 | * Chat and Discussion — _Connect with other users on the Bisq https://bisq.community[Forum], https://webchat.freenode.net/?channels=bisq[IRC], https://keybase.io/team/bisq[Keybase], etc_ 37 | * Charts and Data — _Explore Bisq https://markets.bisq.network[markets], https://bisq.network/volume[global volume], https://coin.dance/volume/bisq/[regional volume], https://bisq.network/release-stats[release statistics], etc_ 38 | * Ratings and Reviews — _Read Bisq user experience reports and reviews on sites like https://www.cryptocompare.com/exchanges/bisq/[CryptoCompare]_ 39 | 40 | === Incubating Efforts 41 | 42 | * Bisq HTTP API — _Automate trading and interact programmatically with your Bisq node_ 43 | * <> — _Get alerts for new offers, trades in process, and more right on your phone_ 44 | 45 | == Contributor Docs 46 | 47 | * <> — _The one-stop doc to help you start contributing to Bisq._ 48 | * <> — _How to get paid for your contributions to Bisq._ 49 | * https://bisq.wiki/Proposals[Proposals^] image:external-link-ltr-icon-grey.svg[external-link,13,13] 50 | * <> 51 | ** <> 52 | * <> 53 | * <> 54 | 55 | 56 | == Papers 57 | 58 | * <> 59 | 60 | == Specifications 61 | 62 | * <> 63 | 64 | == Archive 65 | 66 | * <> 67 | -------------------------------------------------------------------------------- /intro.adoc: -------------------------------------------------------------------------------- 1 | = A Brief Introduction to Bisq 2 | 3 | video::Fv-eCchzBZA[youtube,start=113,end=1168,width=860,height=480,options="modest"] 4 | 5 | == What Bisq is 6 | 7 | Bisq is a *decentralized bitcoin exchange* best understood in terms of its major component parts: 8 | 9 | 1. Bisq is a cross-platform *desktop application* that allows anyone to buy and sell bitcoin in exchange for national currencies and other cryptocurrencies. 10 | 11 | 2. Bisq is a *trading protocol* that enables individuals to exchange directly with one another over the internet, eliminating the need for trusted third party exchange services. 12 | 13 | 3. Bisq is the *peer-to-peer network* formed by Bisq applications discovering, connecting to, and working with one another to implement the Bisq trading protocol. The Bisq network is _fully_ peer-to-peer in that it requires no centrally-controlled servers and has no single points of failure. 14 | 15 | Bisq is *not a company*. Bisq is *free software* released under version 3 of the GNU Affero General Public License. Bisq is _built_ by individuals around the world who choose to work together, and Bisq is _used_ by individuals around the world who choose to trade with Bisq over many other exchange alternatives. 16 | 17 | == Why Bisq exists 18 | 19 | Bisq's mission is to provide a *secure*, *private* and *censorship-resistant* way of exchanging bitcoin for national currencies and other cryptocurrencies over the internet. 20 | 21 | When we say *secure*, we are referring to the safety of users' funds. Today, most bitcoin exchanges are _centralized_, requiring users to store their bitcoins--for at least some amount of time--on exchange servers. When thousands of users do this, it creates extreme incentives for those servers to be hacked and for those users' bitcoins to be stolen. And time and time again these hacks and thefts are exactly what happen. 22 | 23 | When we say *private*, we are referring to users' ability to control access to their own information. Today, most centralized exchanges require users to divulge personally identifying information in order to set up an account, and then in turn link users' trading activity to their respective identities. This practice creates extreme risks for users that their personal details and financial information will be stolen, leaked or otherwise used against their own best interests. 24 | 25 | When we say *censorship-resistant*, we are referring to users' ability to voluntarily trade with one another without interference from a third party. Today, centralized bitcoin exchanges are highly susceptible to such interference. By their nature, they must operate within one legal jurisdiction or another, putting them at risk of being fined or shut down if they do not comply with the laws and other rules of that jurisdiction, which may include restrictions on who can trade and what can be traded, and almost always include requirements to collect personal information as described above. 26 | 27 | What's needed is an exchange where *users keep control of funds*, that *is private by default*, and that *defends freedom of transaction*. We built Bisq to meet these needs. 28 | 29 | Where Bitcoin's motto is "be your own bank," Bisq's is "*be your own exchange.*" 30 | 31 | == How Bisq works 32 | 33 | === In a nutshell 34 | 35 | Imagine you want to buy bitcoin (BTC) in exchange for US dollars (USD). In Bisq terminology, you are a _buyer_ of BTC looking for a _seller_ of BTC who will accept USD as payment. To complete such a trade using Bisq, you would follow a series of steps similar to these: 36 | 37 | . You download and run the Bisq application on your laptop or desktop computer 38 | . You configure Bisq with your USD payment method details 39 | . You browse Bisq's offer book for existing offers to sell BTC for USD 40 | . You take an existing offer, agreeing to buy the seller's BTC for your USD 41 | . You send USD from your bank to the seller's bank and indicate you have done so in Bisq 42 | . You and the seller wait for your USD payment to arrive at the seller's bank 43 | . The seller receives your USD and indicates they have done so in Bisq 44 | . You receive the seller's bitcoin and the trade is complete 45 | 46 | TIP: For complete instructions on each of the steps above, read <>. 47 | 48 | These steps can vary in a number of ways depending on whether you wish to buy or sell bitcoin, whether you are the _maker_ or the _taker_ of an offer, which payment methods you have access to, and so on. But in any case, the steps above are rather different than those one would follow to complete a similar trade on a centralized exchange. 49 | 50 | === How trading with Bisq is different 51 | 52 | Beyond the obvious difference that Bisq is a desktop application and not a browser-based web application, the first difference experienced traders will notice is that there is *no automatic order matching* on the Bisq exchange. Rather, Bisq users manually search for and select specific offers they wish to take. This approach enables truly peer-to-peer trade settlement, and ensures that users are in control of which counterparties they trade with. 53 | 54 | Bisq is also unique among decentralized bitcoin exchanges in the way it coordinates *out-of-band fiat payments*. Bisq does not directly integrate with banks or other national currency payment systems in any way. Rather, Bisq's trading protocol orchestrates the process of buyer and seller working together to settle fiat payments _outside of_ the Bisq application, as demonstrated in steps 5–7 of the trading example above. 55 | 56 | These and other differences result in a key tradeoff for Bisq users--one in which *trade settlement takes longer*, but *trading itself is far more secure, private and censorship-resistant*. 57 | 58 | === How Bisq keeps funds secure 59 | 60 | - Bisq is *entirely non-custodial*; users stay in control of fiat and cryptocurrency funds 61 | - Trades include *security deposits* from buyer and seller to prevent fraud 62 | - Trading funds and security deposits are locked in a *2-of-2 multisig escrow* 63 | - Disputes are handled through a *decentralized human mediation and arbitration system* 64 | 65 | === How Bisq keeps data private 66 | 67 | - Using Bisq requires *no registration or centralized identity verification* 68 | - Every Bisq application is a *Tor hidden service* 69 | - Bisq has *no central servers or databases* to record data 70 | - *Data is encrypted* such that trade details are readable only by counterparties 71 | 72 | === How Bisq resists censorship 73 | 74 | - Bisq's network is a *fully distributed P2P network*, and thus difficult to shut down 75 | - Bisq's network is *built on top of Tor*, and thus inherits Tor's own censorship resistance 76 | - *Bisq is code*, not a company; it is not incorporated, and it cannot be disincorporated 77 | 78 | == Next steps 79 | 80 | - Complete the <> guide 81 | - Ask questions in the Bisq https://bisq.community[Forum] or https://keybase.io/team/bisq[Keybase] 82 | - Stay in touch by following https://twitter.com/bisq_network[@bisq_network] on Twitter 83 | -------------------------------------------------------------------------------- /manual-dispute-payout.adoc: -------------------------------------------------------------------------------- 1 | = How to issue a manual dispute payout 2 | 3 | == Introduction 4 | 5 | In rare cases, it can become necessary for an arbitrator to work with a trader to issue a multi-sig payout transaction manually. This doc explains the steps that both the arbitrator and trader must take to make this happen. 6 | 7 | == Arbitrator instructions 8 | 9 | The instructions that follow assume that a trade dispute has already been opened, arbitrated and closed, but that for some reason the payout transaction has not occurred as expected. 10 | 11 | One reason that a payout transaction may not go through is because the "winner" of the dispute (i.e. the trader who is being awarded the trading amount) has not come online since the ticket has been closed. It is necessary for the winner's Bisq client to come online in order to actually sign their part of the 2-of-3 multi-sig transaction. If you believe this is the problem, you should *not* jump straight to a manual payout. You should first: 12 | 13 | 1. Re-open both buyer and seller tickets for this trade using `cmd-U` 14 | 2. Re-close the ticket of the "losing" (i.e. the trader who is *not* receiving the trade amount, this time checking the "Use loser as publisher" checkbox. 15 | 16 | Assuming that the loser comes online, their client will be used to sign the multi-sig transaction and the payout will be issued to the winner. 17 | 18 | If the approach above does not work, and you believe there is no way to issue the payout transaction using normal mechanisms in the Bisq client and protocol, then continue below with the instructions to issue a manual payout. 19 | 20 | [TIP] 21 | .Fill this out as you go 22 | ==== 23 | Paste the following into a text editor and fill out the individual values as you follow the steps below. You'll use these values when submitting the actual manual payout form in <>. 24 | ---- 25 | depositTxHex: 26 | buyerPayoutAmount: 27 | sellerPayoutAmount: 28 | arbitratorPayoutAmount: 29 | Tx fee: 30 | buyerAddressString: 31 | sellerAddressString: 32 | arbitratorAddressString: 33 | buyerPrivateKeyAsHex: 34 | sellerPrivateKeyAsHex: 35 | arbitratorPrivateKeyAsHex: 36 | buyerPubKeyAsHex: 37 | sellerPubKeyAsHex: 38 | arbitratorPubKeyAsHex: 39 | P2SHMultiSigOutputScript: 40 | ---- 41 | ==== 42 | 43 | === Step 1. Review dispute details 44 | 45 | In `Support > Arbitrator's support tickets`, find the trade dispute in question, select it, and *review the closing chat message to determine who was the "winner" of the dispute*, i.e. who was supposed to have received the trading amount payout. For example, the closing comments on the dispute below make it clear that it was the seller who won the dispute: 46 | 47 | image:images/determine-winner.png[determining who was the winner] 48 | 49 | If the seller was the winner, you will need to work with the seller to issue the manual payout, meaning you will need the seller's public and private key pair as opposed to the buyer's. For simplicity's sake, the instructions in the remainder of this document assume the seller as the winner. You will need to adjust these instructions accordingly if it was in fact the buyer who was the winner. 50 | 51 | While looking at the closing chat message, *take note of the payout amounts for both buyer and seller*. You will need these values in steps below. 52 | 53 | image:images/closing-message.png[closing message] 54 | 55 | Next, click the `Details` button on the dispute ticket, and *take note of the BTC address for both buyer and seller*: 56 | 57 | image:images/buyer-seller-address.png[buyer and seller addresses] 58 | 59 | Next, click the `View contract in JSON format` button and *take note of both the `BuyerMultiSigPubKeyHex` and `SellerMultiSigPubKeyHex` values*—you will need both when filling out the payout form: 60 | 61 | image:images/get-pubkey-hex.png[get pubkey hex value] 62 | 63 | Also *take note of the `txFee` value in the contract JSON*, e.g.: 64 | 65 | "txFee": 36000, 66 | 67 | This is the value of the Bitcoin transaction fee denominated in satoshis. Later, *you will need the same transaction fee value denominated in BTC*, which can be found by dividing the satoshi value by 100,000,000, e.g.: 68 | 69 | 36000/100000000 = 0.00036000 BTC 70 | 71 | Next, close the JSON contract window and click on the `Deposit transaction ID` link in the dispute details dialog to open it in a block explorer (e.g. blockchain.info as shown below). In transaction details web UI, click on the "Show scripts" link and *take note of the P2SH multi-sig output script hex value*: 72 | 73 | image:images/p2sh-multisig-output-script.png[P2SH multisig output script] 74 | 75 | === Step 2. Get arbitrator's public and private key 76 | 77 | *Remove your wallet password* (by following the same steps as found in <> in the trader instructions section). 78 | 79 | *Open the Wallet Data* dialog with `cmd-j` and *check the `Include private keys` checkbox*. 80 | 81 | *Copy the contents of the Wallet Data dialog* and paste it into a text editor. 82 | 83 | Note the `ARBITRATOR` address at the top of the file in the BTC Wallet Address entry list, i.e. the entry with `address=1DBX...` below. This address should be the same as the one that you receive funds to as an arbitrator: 84 | 85 | BTC Wallet: 86 | Address entry list: 87 | AddressEntry{offerId='null', context=ARBITRATOR, address=1DBX...} 88 | AddressEntry{offerId='null', context=AVAILABLE, address=1HN2...} 89 | 90 | Now search the file for the first match for the string `addr:1DBX...`. You should find a section that looks like the following: 91 | 92 | Key to watch: xpub... 93 | addr:1ABC... hash160:f778... 94 | DeterministicKey{pub HEX=02ff..., priv HEX=dfc8..., ...} 95 | addr:1DBX... hash160:760d... 96 | DeterministicKey{pub HEX=039d..., priv HEX=929d..., ...} 97 | 98 | *Note both the `pub HEX` and `priv HEX` values for the `addr:1DBX...` entry*, which should be the second entry in the list. 99 | 100 | You can now *reset your wallet password*. 101 | 102 | === Step 3. Get trader's private key 103 | 104 | First, navigate back to the trade dispute ticket in question. *Re-open both buyer and seller tickets* by clicking on each and pressing `cmd-U`. 105 | 106 | Click on the winning trader's dispute ticket and *send the trader their public key* (as determined in the steps above) *as well as a link to the <> section of this document*. Ask them to follow those instructions and to respond to you with their private key value once they have it. 107 | 108 | When you have the trader's private key, move on to the next step. 109 | 110 | [[issue-payout]] 111 | === Step 4. Issue the manual dispute payout 112 | 113 | Now that you have all the necessary information, you can *open the Emergency multisig payout tool* by clicking `alt-g` in the dispute view: 114 | 115 | image:images/multisig-payout-tool.png[Emergency multi-sig payout tool] 116 | 117 | depositTxHex:: The Deposit transaction ID from the Dispute details view, i.e. the same transaction ID you clicked on to view the transaction in a block explorer. 118 | 119 | buyerPayoutAmount:: The amount in BTC that the buyer should be paid out, as noted above, e.g. `0.03` 120 | 121 | sellerPayoutAmount:: The amount in BTC the seller should be paid out, e.g. `0.0662` 122 | 123 | arbitratorPayoutAmount:: This value should always be `0`, as we no longer issue payouts to arbitrators 124 | 125 | Tx fee:: The value of the `txFee` taken from the JSON contract details above, after converting from satoshis to BTC, e.g. `36000` satoshis => `0.00036` BTC 126 | 127 | buyerAddressString:: The buyer's bitcoin address 128 | 129 | sellerAddressString:: The seller's bitcoin address 130 | 131 | arbitratorAddressString:: The arbitrator's bitcoin address 132 | 133 | buyerPrivateKeyAsHex:: The buyer's private key (leave empty if buyer was not the winner) 134 | 135 | sellerPrivateKeyAsHex:: The seller's private key (leave empty if seller was not the winner) 136 | 137 | arbitratorPrivateKeyAsHex:: The arbitrator's private key 138 | 139 | buyerPubKeyAsHex:: The buyer's public key 140 | 141 | sellerPubKeyAsHex:: The seller's public key 142 | 143 | arbitratorPubKeyAsHex:: The arbitrator's public key 144 | 145 | P2SHMultiSigOutputScript:: The P2SH multi-sig output script hex value as copied from the block explorer 146 | 147 | When all values have been entered (and double-checked!), click `Sign and publish transaction` to issue the payout. 148 | 149 | When you have confirmed that the payout transaction worked as expected, *let the trader know and close out the re-opened buyer and seller tickets*. 150 | 151 | 152 | == Trader instructions 153 | 154 | [WARNING] 155 | The instructions below require you to share sensitive private key information with your arbitrator in order to assist in a manual multi-sig payout. This is necessary only in extraordinary situations, e.g. when a bug or network issue has caused the normal, automated multi-sig payout process to fail. In the unlikely event that you do need to follow these instructions, *you should never share private key information with anyone other than your arbitrator*, and *you should send your private key information only via the Bisq support ticket chat interface*. Also note that the private key the arbitrator is requesting from you is specific to the trade in question. All other trades and funds in your Bisq wallet have different addresses and different private keys. 156 | 157 | === Step 1. Get your public key from your arbitrator 158 | 159 | Your arbitrator will follow the link:#arbitrator-instructions[instructions] above to determine which of your public keys was used to participate in the multi-sig transaction. 160 | 161 | Wait for your arbitrator to provide you with this value. They will send it to you via the Bisq support ticket chat interface. When you have received the public key from the arbitrator, move on to the next step. 162 | 163 | === Step 2. Remove your wallet password [[remove-password]] 164 | 165 | Removing your wallet password is necessary in order to get the unencrypted value of your corresponding private key in the next step. 166 | 167 | Go to `Account > Wallet Password`, enter your password and click the `Remove password` button: 168 | 169 | image:images/password-active.png[wallet password active] 170 | 171 | When your wallet password has been removed, you should see the following: 172 | 173 | image:images/password-removed.png[wallet password removed] 174 | 175 | You can now move on to the next step. 176 | 177 | === Step 3: Send your private key to your arbitrator 178 | 179 | Press `cmd+j` on macOS or `ctrl-j` on Windows to *open Bisq's Wallet Data dialog*. You should see a screen similar to the following: 180 | 181 | image:images/wallet-data.png[wallet data dialog] 182 | 183 | At the bottom of the dialog, *check the box that reads `Include private keys`*: 184 | 185 | image:images/include-private-keys.png[include private keys] 186 | 187 | Then *click `Copy to clipboard`*. 188 | 189 | Open the text editor of your choice, e.g. TextEdit on macOS or Notepad on Windows, and *paste the copied wallet data text* into it. 190 | 191 | In the text editor, *search for the public key value your arbitrator provided* in step one above. You're looking for an entry that reads `DeterministicKey{pub HEX="..."`, where `...` is the public key. It should be the first search result in the file. 192 | 193 | When you have found this entry, select and *copy the `priv HEX=...` value* that immediately follows the `pub HEX` value. *This value is your private key*. 194 | 195 | Close the text editor. When prompted, *do not save the file*. 196 | 197 | Back in your Bisq client, *send your private key to your arbitrator* by pasting it into the support ticket chat window. 198 | 199 | Your arbitrator will take over from here, and use your private key to issue the multi-sig payout. They will stay in touch with you to let you know when it is complete. 200 | 201 | === Step 4: Reset your wallet password 202 | 203 | The final step is to reset your wallet password. 204 | 205 | Go to `Account > Wallet Password`, enter and confirm your password and click `Set password`. 206 | -------------------------------------------------------------------------------- /payment-methods.adoc: -------------------------------------------------------------------------------- 1 | = Payment Methods 2 | :imagesdir: ./images 3 | :toc: 4 | :high-risk: 0.25 BTC 5 | :mid-risk: 0.50 BTC 6 | :low-risk: 1.00 BTC 7 | :very-low-risk: 2.00 BTC 8 | 9 | There are several payment methods you can use to buy and sell bitcoin with Bisq. This doc covers the details and limitations of each. 10 | 11 | Every offer on Bisq designates a payment method for traders to settle payments. The Bisq software does not actually integrate with any payment methods—all non-bitcoin fund transfers are made outside of the Bisq software. 12 | 13 | But unlike cryptocurrencies, fiat payment methods are riddled with flaws and limitations that require Bisq to employ several measures to encourage traders to carry out their parts of the deal quickly and honestly. 14 | 15 | Among these measures are (1) limits that correspond to payment account risk profiles and (2) an account-signing mechanism to cultivate a network of trusted payment accounts. 16 | 17 | == Supported Fiat Payment Methods 18 | 19 | Over 20 payment methods are supported to buy and sell bitcoin with Bisq using national currencies. These payment methods vary in chargeback risk, regional availability, transaction size, fees, privacy, verifiability, and other characteristics. 20 | 21 | The top consideration for maintaining payment methods is chargeback risk. PayPal, Venmo, and Cash App are not supported on Bisq because chargebacks for payments made with those services are relatively easy. 22 | 23 | We welcome suggestions for new payment methods on Bisq, especially for those that enable new markets. Documentation on the criteria and process for adding new payment methods https://github.com/bisq-network/bisq-docs/issues/172[is forthcoming^]. For now, feel free to make suggestions by reaching out on https://keybase.io/team/bisq[Keybase^]. 24 | 25 | Below is a list of fiat payment methods Bisq currently supports. 26 | 27 | CAUTION: The maximum trade sizes listed below are not available for most newly-created payment accounts. Please see the <<#account-signing, Account Signing>> section below for details on how to enable bigger trade sizes for your payment accounts. 28 | 29 | |=== 30 | |Payment Method |Region |Trading Period |Per-Trade Limit|Notes 31 | 32 | |Advanced Cash* 33 | |Global 34 | |1 day 35 | |{very-low-risk} 36 | |Not available in the USA 37 | 38 | |Alipay* 39 | |China 40 | |1 day 41 | |{low-risk} 42 | | 43 | 44 | |Cash Deposit* 45 | |N/A 46 | |4 days 47 | |{high-risk} 48 | |Some banks don't accept cash deposits from non-customers 49 | 50 | |Chase QuickPay 51 | |USA 52 | |1 day 53 | |{high-risk} 54 | | 55 | 56 | |Face-to-Face (F2F)* 57 | |Global 58 | |4 days 59 | |{low-risk} 60 | | 61 | 62 | |Faster Payments* 63 | |UK 64 | |1 day 65 | |{high-risk} 66 | | 67 | 68 | |HalCash* 69 | |Spain 70 | |1 day 71 | |{low-risk} 72 | | 73 | 74 | |Interac e-Transfer 75 | |Canada 76 | |1 day 77 | |{high-risk} 78 | | 79 | 80 | |Japan Zengin Furikomi* 81 | |Japan 82 | |1 day 83 | |{low-risk} 84 | | 85 | 86 | |MoneyBeam (N26) 87 | |Europe 88 | |1 day 89 | |{high-risk} 90 | | 91 | 92 | |MoneyGram* 93 | |Global 94 | |4 days 95 | |{mid-risk} 96 | | 97 | 98 | |National Bank Transfer 99 | |N/A 100 | |4 days 101 | |{high-risk} 102 | | 103 | 104 | |Perfect Money* 105 | |Europe and USA 106 | |1 day 107 | |{low-risk} 108 | | 109 | 110 | |Popmoney 111 | |USA 112 | |1 day 113 | |{high-risk} 114 | | 115 | 116 | |PromptPay* 117 | |Thailand 118 | |1 day 119 | |{low-risk} 120 | | 121 | 122 | |Revolut 123 | |Global 124 | |1 day 125 | |{high-risk} 126 | | 127 | 128 | |SEPA 129 | |Europe 130 | |6 days 131 | |{high-risk} 132 | | 133 | 134 | |SEPA Instant 135 | |Europe 136 | |1 day 137 | |{high-risk} 138 | | 139 | 140 | |Swish* 141 | |Sweden 142 | |1 day 143 | |{low-risk} 144 | | 145 | 146 | |Transfer with Same Bank 147 | |N/A 148 | |2 days 149 | |{high-risk} 150 | | 151 | 152 | |Transfer with Specific Banks 153 | |N/A 154 | |4 days 155 | |{high-risk} 156 | | 157 | 158 | |US Postal Money Order* 159 | |USA 160 | |8 days 161 | |{high-risk} 162 | |Maximum is $1,000 per money order within the USA 163 | 164 | |Uphold 165 | |Global 166 | |1 day 167 | |{high-risk} 168 | | 169 | 170 | |WeChat Pay* 171 | |China 172 | |1 day 173 | |{low-risk} 174 | | 175 | 176 | |Western Union* 177 | |Global 178 | |4 days 179 | |{mid-risk} 180 | | 181 | 182 | |Zelle 183 | |USA 184 | |4 days 185 | |{high-risk} 186 | | 187 | 188 | |=== 189 | 190 | +++* These payment methods do not need to be signed to attain buying limits higher than 0.01 BTC (see account signing below for more details).+++ 191 | 192 | == Account Signing 193 | 194 | Payment account _aging_ is the primary mechanism that determines how much bitcoin can be bought or sold with a particular payment account. For some types of payment accounts, account _signing_ determines when that aging begins. 195 | 196 | For lower-risk payment accounts, aging begins right away, as soon as the payment account is created in Bisq—no signing is required. 197 | 198 | For higher-risk payment accounts, aging begins only when the payment account is signed by a trusted peer. **Until 30 days _after_ this signing, maximum buy size is 0.01 BTC**. 199 | 200 | For all accounts, limits on selling bitcoin follow account aging and are not affected by account signing. 201 | 202 | [NOTE] 203 | .How does account aging work? 204 | ==== 205 | With plain account aging (without account signing), trade limits for buying and selling phase in over 2 months _since the account was created in Bisq_. 206 | 207 | * Account age <30 days: trade limit is 25% of the maximum 208 | * Account age 30-60 days: trade limit is 50% of the maximum 209 | * Account age >60 days: trade limit is 100% of the maximum 210 | 211 | Western Union, for example, has a maximum trade size of 0.5 BTC. Upon creation, and until 30 days have passed since creation, a new Western Union account will be limited to buying and selling 0.125 BTC. After 30 days have passed since account creation, the account will be limited to buying and selling 0.25 BTC. Then after 60 days have passed since account creation, the account will be able to trade 0.50 BTC. 212 | 213 | You can see details on the `AccountAgeWitness` object that enables this aging mechanism <>. 214 | ==== 215 | 216 | === When Account Signing is Required 217 | 218 | Payment accounts are considered to have higher risk if they meet both of the following conditions: 219 | 220 | 1. the payment account will be used to buy or sell bitcoin for a major national currency market on Bisq (USD, EUR, CAD, GBP, AUD, BRL) 221 | 2. the payment account has chargeback risk (SEPA, SEPA Instant, Interac e-Transfer, Zelle, Revolut, Chase QuickPay, Popmoney, MoneyBeam, Uphold, and any kind of bank transfer) 222 | 223 | In major national currency markets, account signing is not required to enable account aging for face-to-face trading, cash deposits, money orders (US Postal Money Orders, MoneyGram, Western Union) or Advanced Cash. 224 | 225 | In other markets, account signing is not currently required for any payment methods. 226 | 227 | === How To Have a Payment Account Signed 228 | 229 | A signed payment account indicates that it can be trusted to engage in trades honestly, and as a result, is allowed higher trading limits. 230 | 231 | WARNING: Account signing does not _guarantee_ problem-free trading. Instead, it creates a trusted network of accounts where it is _unlikely_ to encounter a scammer. 232 | 233 | **Please note that account signing works per payment account.** Having one payment account signed does not affect trading limits on your other payment accounts. You need to go through the account signing process below for each payment account you want to lift limits for. 234 | 235 | Here's how to have a payment account signed for higher bitcoin buying limits. 236 | 237 | 1. **Take an offer to buy bitcoin.** This offer must be from a trading peer with a signed payment account who is able to sign other payment accounts. 238 | + 239 | If a trading peer is capable of signing your payment account, they'll have a check mark on their offer listing in the `Time since signing` column. 240 | + 241 | image::peer-can-sign-offer-listing.png[Look for this indicator.,400,400] 242 | + 243 | You can click the trading peer's avatar to see more details on the account signing. 244 | + 245 | image::account-signing-details-pop.png[Look for this indicator.,400,400] 246 | + 247 | [NOTE] 248 | .How were the first payment accounts signed if there were no peers to sign them? 249 | ==== 250 | Bisq arbitrators signed a collection of accounts that met certain criteria to bootstrap the network of trusted payment accounts just before the v1.2 release. 251 | 252 | The following criteria were determined to balance high integrity with volume (so that there were a sufficient number of signed peer accounts available to sign other peer accounts in the beginning): 253 | 254 | * payment account must be older than 60 days 255 | * payment account must have been involved in a dispute as a bitcoin buyer, and received bitcoin as an outcome of that dispute (thereby proving that a successful fiat _payment_ took place) 256 | 257 | All payment accounts that met the 2 criteria above were signed by arbitrators and immediately able to sign other payment accounts upon the release of v1.2. 258 | ==== 259 | 260 | 2. **Successfully settle the trade.** When you send your fiat payment to the seller, your payment account will be signed when the seller clicks the `Confirm payment received` button. 261 | + 262 | Thirty days after signing, the following will take place: 263 | + 264 | -- 265 | * the 0.01 BTC buying limit will be lifted 266 | * trading limits will apply as if account aging began at the time of signing 267 | * you will be able to sign other payment accounts 268 | -- 269 | + 270 | NOTE: The purpose of the 30-day delay is to allow time for chargebacks, as the typical trade period is often not long enough for fraudulent charges to be detected. This is why you should send payment as quickly as possible when looking to get signed, and why sellers will take as long as possible (within the trade period) to confirm your payment on their end. 271 | + 272 | To clarify how trading limits apply, let's look at a concrete example with SEPA. SEPA payments have a maximum trade size of 0.25 BTC. With plain account aging, this limit would phase in over 3 months after account creation. The limit would be 0.0625 BTC in the first month, 0.125 BTC in the second month, and 0.25 BTC afterward. To see how account signing changes this, let's assume we create a SEPA payment account on 01 January 2020. Then let's assume that the account is not signed until 01 March 2020. Even though the account is 60 days old at the time of signing, it will retain its 0.01 BTC buy limit through January, February, _and_ March. Then, on 01 April 2020 (30 days after signing), the payment account will drop its 0.01 BTC limit and take on a 0.125 BTC trade limit. Why? Because at that point, it's over 30 days old _as of the date it was signed_. 273 | 274 | 3. **Sign other users.** No one likes 0.01 BTC limits, and many users will want to be signed by a peer with a trusted account. Once you're signed, please try to maintain some offers to give unsigned buyers a chance to be signed to broaden the trusted network. 275 | 276 | === Things to Note 277 | 278 | * Selling limits are unaffected by account signing, and instead follow account aging. This means you can create a payment account to sell bitcoin using a risky payment method and sell 0.0625 BTC right away. You will only be able to _buy_ 0.01 BTC with that account, however, until it is signed. 279 | + 280 | There's a field in payment account details that specified exactly what your payment account limits are. 281 | + 282 | image::account-signing-limit-details.png[Payment account limit details.,400,400] 283 | 284 | * Additional methods to have a payment account signed without a delay are in discussion (see https://github.com/bisq-network/proposals/issues/93[here^] and https://github.com/bisq-network/proposals/issues/83[here^]). 285 | 286 | == Altcoin Payment Methods 287 | 288 | Bisq also supports a variety of other cryptocurrencies for buying and selling bitcoin. Because such fund transfers are irreversible and relatively quick, altcoin trade sizes are 2 BTC across the board (no account signing or account aging necessary) with a 1-day trade period. 289 | 290 | === Altcoins Instant 291 | 292 | image::altcoins-instant.png[Make an Altcoins Instant account.,400,400] 293 | 294 | When creating an altcoin payment account on Bisq, you can opt to make it for Instant offers. Instant offers are just like regular offers—all typical <> apply—but the **trade period is 1 hour** instead of 1 day. 295 | 296 | TIP: Don't forget to disable Instant offers when you're away from your computer! 297 | 298 | Instant accounts can only be used to make and take Instant offers, so you'll probably want to create a regular altcoin account to make and take regular offers too. 299 | 300 | == See Also 301 | 302 | * https://github.com/bisq-network/bisq/blob/master/core/src/main/java/bisq/core/payment/payload/PaymentMethod.java 303 | * https://en.bitcoin.it/wiki/Payment_methods 304 | -------------------------------------------------------------------------------- /proposals.adoc: -------------------------------------------------------------------------------- 1 | = Proposals 2 | 3 | Proposals are a means for suggesting changes to Bisq Network software components, infrastructure and processes. 4 | 5 | 6 | == Introduction 7 | 8 | The Bisq DAO is a flat organization, with no command-and-control hierarchy available to make big decisions and carry them out. Usually this is not a problem, as most day-to-day changes happen without any need for organization-wide consensus. Certain kinds of changes, however, benefit from or even require it. 9 | 10 | What's needed is a mechanism that allows any contributor to _propose_ a change, and all other contributors to _review_ it in order to arrive at an IETF-style rough consensus.footnote:[See link:https://en.wikipedia.org/wiki/Rough_consensus[]] _Proposals_ are that mechanism, and this document covers everything that participants need to know about the process. 11 | 12 | === What proposals are good for 13 | 14 | * Creating an entire new Bisq component or making a significant change to an existing one 15 | * Changing something about the way contributors work together 16 | 17 | === What proposals are not good for 18 | 19 | * Smaller changes to existing components, infrastructure or processes, where a broad consensus of contributors is not required 20 | 21 | 22 | == Infrastructure 23 | 24 | === GitHub 25 | 26 | Proposals are managed as GitHub issues in the {gh-org}/proposals/issues[bisq-network/proposals] repository. 27 | 28 | === Keybase 29 | 30 | The `#proposals` Keybase channel is available for discussion and notifications about proposal issue activity. 31 | 32 | 33 | == Roles 34 | 35 | === Submitter 36 | 37 | The contributor(s) who write a proposal and carry it through to completion. 38 | 39 | **Submitters are 100% responsible for the success of their proposals.** 40 | 41 | === Reviewer 42 | 43 | Other contributors who read, discuss and react to proposals. 44 | 45 | **Any contributor _may_ review a proposal, but no contributor is obligated to do so.** This intentionally puts the onus on the submitter to ensure their proposal is relevant and well-written per the <> below. 46 | 47 | === Maintainer 48 | 49 | The contributor(s) responsible for proposals <> and <>.footnote:[See link:roles.html#maintainer[]] 50 | 51 | ==== Role Issue 52 | 53 | {gh-org}/roles/issues/30[bisq-network/roles#30] footnote:[See link:roles.html#issue[]] 54 | 55 | ==== Role Team 56 | :proposals-maintainers: {gh-team}/proposals-maintainers[@bisq-network/proposals-maintainers] 57 | 58 | {proposals-maintainers} footnote:[See link:roles.html#team[]] 59 | 60 | ==== Duties 61 | 62 | * Enforce the proposals <> detailed below. 63 | * Monitor communications on the `#proposals` Keybase channel.footnote:[See link:roles.html#communication[]] 64 | * Keep this proposals documentation up to date.footnote:[See link:roles.html#documentation[]] 65 | * Write a monthly report on the proposals maintainer <>.footnote:[See link:roles.html#reporting[]] 66 | 67 | ==== Rights 68 | 69 | * Write access to the {gh-org}/proposals[bisq-network/proposals] repository. 70 | 71 | 72 | == Process 73 | 74 | === Step 0. Research 75 | 76 | Before you submit a proposal, **do your homework!** 77 | 78 | . Discuss your idea with other contributors to see if a proposal is worth submitting at all; 79 | . Search through existing proposals (both https://github.com/bisq-network/proposals/issues?utf8=%E2%9C%93&q=is%3Aissue+[open and closed]) to see whether something similar has already been proposed; 80 | . Notice which among those proposals have been accepted and rejected, and why; 81 | . Read this document to fully understand the proposal process and guidelines. 82 | 83 | === Step 1. Submit 84 | 85 | Create a new GitHub issue in the `bisq-network/proposals` repository containing the text of your proposal, written and formatted per the guidelines below. 86 | 87 | A maintainer will quickly review your proposal and will either (a) assign it to you to indicate your ownership and responsibility over it, or (b) close it and label it as `was:incorrect` if it does not follow the guidelines below. 88 | 89 | === Step 2. Review 90 | 91 | Once a proposal is submitted, a two-week review period follows. During this period, interested reviewers should read, discuss and ultimately https://help.github.com/articles/about-conversations-on-github/#reacting-to-ideas-in-comments[react] to the proposal as follows: 92 | 93 | - 👍: I agree with the proposal and want to see it enacted 94 | - 😕: I am uncertain about the proposal and I need more information 95 | - 👎: I disagree with the proposal and do not want to see it enacted 96 | 97 | When reacting with a 😕 or 👎, add a comment explaining why. If you don't, then don't expect your opinion to have much weight or get addressed. 98 | 99 | If you do not understand or care about a given proposal, ignore it. 100 | 101 | Use comments on the proposal issue to discuss, ask questions, and get clarifications. Take lengthy discussions offline to Keybase or elsewhere and then summarize them back on the issue. 102 | 103 | NOTE: Remember that the proposal review process is all about reaching a _rough consensus,_ meaning that there is a broad agreement that the proposal should be enacted, and that any dissenting opinions have been addressed, though not necessarily fully resolved. 104 | 105 | === Step 3. Evaluate 106 | 107 | After the two-week review period is over, a maintainer will evaluate reactions to and discussions about the proposal and will close the issue with a comment explaining that it is approved or rejected based on whether a rough consensus was achieved. 108 | 109 | Approved proposals will be labeled with `was:approved`. Rejected proposals will be labeled with `was:rejected`. 110 | 111 | If rough consensus has not been achieved, e.g. because discussion is still ongoing, dissenting concerns have not been addressed, or the proposal has turned out to be contentious, the maintainer will indicate that they cannot close the proposal, and that it is up to the submitter to take next steps to move the proposal forward. If the proposal does not move forward after another two weeks, the maintainer will close and label it `was:stalled`. 112 | 113 | If there have been no or very few reactions to a proposal after the two-week period, the maintainer will close it and label it as `was:ignored`. 114 | 115 | === Step 4. Enact 116 | 117 | Assuming your proposal was approved, the next step is to actually enact the changes described in that proposal. 118 | 119 | 120 | == Guidelines 121 | 122 | Write your proposal in a way that makes it as easy as possible to achieve rough consensus. This means that **proposals should be as simple, focused, concrete and well-defined as possible.** Your goal should be to make it as easy as possible for your fellow contributors to understand and agree with you. 123 | 124 | **Take full responsibility for your proposal.** It is not the maintainers' job, nor anyone else's, to see your proposal succeed. If people aren't responding or reacting to your proposal, it's your job to solicit that feedback more actively. 125 | 126 | **Never assume that anyone other than yourself is going to do the work described in your proposal.** If your proposal does place expectations on other contributors, or requires them to change their behavior in any way, be explicit about that. 127 | 128 | **Provide context.** Make a strong case for your proposal. Link to prior discussions. Do not make your reader do any more work than they have to to understand your proposal. 129 | 130 | **Format your proposal in Markdown.** Make it a pleasure to read. 131 | 132 | In general, **good proposals take time to research and write.** Every minute you spend clearly and logically articulating your proposal is a minute that you save other contributors in understanding it. This diligence on your part will be appreciated and rewarded by others' attention. Cheaply written, "drive by" proposals that waste others' time will be closed immediately as `was:incorrect`. 133 | -------------------------------------------------------------------------------- /roles.adoc: -------------------------------------------------------------------------------- 1 | = Roles 2 | 3 | Roles are the way contributors take responsibility for Bisq Network resources and processes. 4 | 5 | 6 | == Introduction 7 | 8 | There are many resources and processes vital to the operation of the Bisq Network that require ownership by individual contributors. For example, someone must merge pull requests into the `bisq-desktop` repository, someone must manage DNS for the `bisq.network` domain, someone must conduct monthly stakeholder voting, and so on. 9 | 10 | This document defines the system of _roles_ used within the Bisq DAO to enumerate, define and track each of these responsibilities. The system is designed with two major goals in mind: 11 | 12 | . To maximize role owner autonomy in order to achieve <> decentralization goals. 13 | . To maximize transparency such that DAO stakeholders can effectively review and vote on role owner compensation requests. 14 | 15 | 16 | == Properties 17 | 18 | The following are properties common to all roles. 19 | 20 | === Duties 21 | 22 | _Duties_ are actions that must be performed for a certain resource or process to function normally. 23 | 24 | For example, a repository maintainer's duties include merging pull requests in a timely fashion, and a website operator's duties include keeping the site available at all times. 25 | 26 | === Rights 27 | 28 | _Rights_ are special permissions or other access required to perform the <> of a role. 29 | 30 | For example, a repository maintainer's rights include write permissions to their repository, and a website operator's rights include administrative access to site hosting infrastructure. 31 | 32 | === Owners 33 | 34 | _Owners_ are contributors who have the <> required to perform the <> of a role. 35 | 36 | One owner is designated as _primary_ and any other owners are designated as _secondary_.footnote:[See {gh-org}/proposals/issues/12] The primary is responsible for performing the <> of the role, while secondaries stand by, ready to take over for the primary at any time. 37 | 38 | 39 | == Infrastructure 40 | 41 | The following infrastructure is used to define and manage each role. 42 | 43 | === Docs 44 | 45 | Each role should be documented at https://docs.bisq.network[docs.bisq.network], not in a document of its own, but in a _section_ of a document dedicated to the larger resource or process in question. 46 | 47 | For example, there is no "Proposals Maintainer" document, but rather there is a <> document having a <> section within. 48 | 49 | Each role's documentation should enumerate its <> and <> and link to its <> and <>. 50 | 51 | === Team 52 | 53 | Each role has a dedicated GitHub team where each of the role's <> are members. The team is used to manage access to GitHub repositories that the role is responsible for and to send notifications to role owners with @mentions in GitHub issues and pull requests. 54 | 55 | For example, the {gh-team}/desktop-maintainers/members[@bisq-network/desktop-maintainers] team has write access to the {gh-org}/bisq-desktop[bisq-network/bisq-desktop] repository. 56 | 57 | NOTE: GitHub teams are visible only to GitHub organization members. To join the {gh-org}[@bisq-network] org, see the <>. 58 | 59 | The primary role owner is also assigned as the _maintainer_ of their role's GitHub team, such that they may manage the team without requiring the intervention of a GitHub admin. 60 | 61 | === Issue 62 | 63 | Each role has a dedicated GitHub issue in the {gh-org}/roles/issues[bisq-network/roles] repository, wherein: 64 | 65 | - The **Assignees** field is used to track role ownership. 66 | - The **Description** field is used to link to the role's <>, <> and primary <>. 67 | - **Comments** are used for <> and feedback. 68 | 69 | See the {role}/30[Proposals Maintainer] role issue for an example. 70 | 71 | 72 | == Types 73 | 74 | Most roles fit into one of the types below. 75 | 76 | === Maintainer 77 | 78 | A _Maintainer_ is a contributor responsible for enforcing process in a given GitHub repository. 79 | 80 | Examples: {role}/63[Bisq Desktop Maintainer], {role}/30[Proposals Maintainer]. 81 | 82 | ==== Maintainer Duties 83 | 84 | * Merging or closing pull requests after sufficient review. 85 | * Tagging releases. 86 | * Triaging incoming issues and keeping them organized over time. 87 | 88 | [IMPORTANT] 89 | .A Maintainer is not a Developer or a Reviewer 90 | ==== 91 | Submitting and reviewing pull requests is something any contributor can do; neither are maintainer duties per se. 92 | 93 | This is particularly important from a <> perspective. **If you are a maintainer, do NOT group your development and review activities together with your maintainer role in your compensation requests.** Rather, account for them separately like any other contributor would. 94 | 95 | The goal is to have as many competent contributors developing and reviewing as possible, not to load everything on the maintainer. https://rfc.unprotocols.org/spec:1/C4/#21-preliminaries[C4] is the inspiration here, it's worth (re-)reading. 96 | ==== 97 | 98 | ==== Maintainer Rights 99 | 100 | * Write access to the repository they are responsible for. 101 | 102 | === Operator 103 | 104 | An _Operator_ is a contributor responsible for keeping a given resource running and functioning normally. 105 | 106 | Examples: {role}/19[Forum Operator], {role}/14[Bisq Pricenode Operator]. 107 | 108 | ==== Operator Duties 109 | 110 | * Keep the given resource online and functioning normally. 111 | * Keep the resource up to date with latest version. 112 | * Maintain backups as appropriate. 113 | * Report on any incidents. 114 | 115 | ==== Operator Rights 116 | 117 | * Administrative access to hosting infrastructure. 118 | * Ownership of any domain name used. 119 | 120 | === Administrator 121 | 122 | An _Administrator_ ('Admin') is a contributor responsible for managing a given resource. 123 | 124 | Examples: {role}/16[GitHub Admin], {role}/23[Keybase Admin]. 125 | 126 | ==== Admin Duties 127 | 128 | * Respond to change requests. 129 | 130 | ==== Admin Rights 131 | 132 | * Access to the administrative interface of the resource in question. 133 | 134 | === Moderator 135 | 136 | A _Moderator_ is a contributor responsible for enforcing process and standards in a given communications channel. 137 | 138 | Examples: {role}/37[Bitcointalk Moderator], {role}/25[Reddit Moderator]. 139 | 140 | ==== Moderator Duties 141 | 142 | * Ensure discussions are on topic, civil, etc. 143 | * Post key announcements in a timely fashion. 144 | 145 | ==== Moderator Rights 146 | 147 | * Moderator (or equivalent) status in the channel. 148 | 149 | 150 | == Common duties 151 | 152 | The following duties are common to all roles. 153 | 154 | === Reporting 155 | 156 | Primary role <> should report once a month in the form of a comment on their <>.footnote:[See {gh-org}/proposals/issues/13] The report should contain whatever information the owner believes would be valuable to other users, contributors and stakeholders. The comment should be formatted in Markdown as follows: 157 | 158 | [source,markdown] 159 | ---- 160 | ## YYYY.MM report 161 | 162 | 163 | 164 | /cc bisq-network/compensation# 165 | ---- 166 | 167 | Where `` is the content of the report itself, and `` is the number of that contributor's monthly compensation request. {role}/16#issuecomment-393852612[Example]. 168 | 169 | Some roles may have nothing to report in a given month. In this case, a report should still be written stating that there is "nothing to report". {role}/18#issuecomment-393217596[Example]. 170 | 171 | === Documentation 172 | 173 | Primary role <> should document changes to their role by submitting pull requests to their role's <>. 174 | 175 | === Communication 176 | 177 | Primary role <> should respond in a timely fashion to feedback comments on their role <>, issues created in their repositories, @mentions of their <>, and questions in their Keybase channel. 178 | 179 | 180 | == Compensation 181 | 182 | Role owners should include a summary line item for each role they own in a monthly <>. Each summary should include: 183 | 184 | . The name of the role, 185 | . a link to the owner's monthly <> for that role, and 186 | . the total amount of BSQ being requested for performing the role's duties during that month. 187 | 188 | [example] 189 | .Per-role line items in a compensation request 190 | ==== 191 | * Bisq Desktop Maintainer: https://github.com/bisq-network/roles/issues/63#issuecomment-401352998[bisq-network/roles#63 (comment)] `(350 BSQ)` 192 | * Bisq Seednode Operator: https://github.com/bisq-network/roles/issues/15#issuecomment-401547205[bisq-network/roles#15 (comment)] `(150 BSQ)` 193 | ==== 194 | 195 | NOTE: Secondary role owners should not submit monthly reports or compensation requests for a role unless they actually performed the duties of that role during that month. 196 | 197 | The amount of BSQ requested should include any hard costs (e.g. hosting) plus time and effort costs involved in performing the duties of the role. These costs should be detailed in the monthly report as follows: 198 | 199 | [example] 200 | .Monthly report for Bisq Desktop Maintainer 201 | ==== 202 | ## 2018.07 report 203 | 204 | * Regular duties `(150 BSQ)` 205 | * Big issue cleanup `(200 BSQ)` 206 | 207 | Total: 350 BSQ 208 | 209 | /cc bisq-network/compensation#42 210 | ==== 211 | 212 | [example] 213 | .Monthly report for Bisq Seednode Maintainer 214 | ==== 215 | ## 2018.07 report 216 | 217 | * Hosting 2 nodes @ 50 USD/mo on Digital Ocean `(100 BSQ)` 218 | * Upgrade nodes to v0.7.1 `(50 BSQ)` 219 | 220 | Total: 150 BSQ 221 | 222 | /cc bisq-network/compensation#42 223 | ==== 224 | 225 | The only work items that should be included in role compensation are those <> that can be performed _only_ by that role's owner. Everything else should be itemized independently. 226 | 227 | For example, as mentioned above in the <> section, a repository maintainer's main duties are merging pull requests and triaging incoming issues. If the person playing the maintainer role submits their own pull requests, or performs reviews of others' pull requests, that work should NOT be grouped together with regular maintainer duties when putting together a compensation request. Rather, each PR submitted or reviewed should be called out separately as individual contributions. 228 | 229 | 230 | == Bonding 231 | 232 | Most roles involve special <> that, if abused, could cause damage to the Bisq Network. For this reason, role owners must put up a _bond_ in BSQ commensurate with the amount of damage that could be caused. In the event of a role owner turning into a bad actor or being grossly negligent, this bond can be confiscated through a BSQ voting process. 233 | 234 | Bonding is not currently in place during <> of the Bisq DAO, but is being implemented and will come online when we go live on Bitcoin testnet. 235 | 236 | 237 | == Processes 238 | 239 | The following are some common roles-related processes. 240 | 241 | === Proposing a new role 242 | 243 | Typically, proposing a new role is one part of a larger proposal to introduce some new resource or process. 244 | 245 | . Discuss the idea informally with other contributors, e.g. via Keybase. 246 | . Follow the <> process to formally suggest the new resource or process. 247 | . Draft documentation for the new resource or process, including a section about the new role as a pull request to the {gh-org}/bisq-docs[bisq-network/bisq-docs] repository. 248 | 249 | For example, see the {gh-org}/proposals/15[proposal to support Tor Relays] and the resulting {role}/72[Tor Relay Operator] role issue. 250 | 251 | === Adding a secondary role owner 252 | 253 | A primary role owner may add a secondary owner with the following steps: 254 | 255 | . Add them as a member of the role's GitHub <>. 256 | . Add them as an assignee to role's GitHub <>. 257 | . Announce the change via a comment on the role's GitHub <>. 258 | 259 | === Transferring role ownership 260 | 261 | A primary owner may transfer ownership to another with the following steps: 262 | 263 | . Grant the _maintainer_ role to the new primary in the role's GitHub <>. 264 | . Remove the _maintainer_ role from yourself. 265 | . Update the role's GitHub <> to reflect the new primary owner. 266 | . Announce the change in a comment on the role's GitHub <>. 267 | 268 | 269 | [[roles-maintainer-role]] 270 | == The Roles Maintainer role 271 | 272 | Roles Maintainers are the contributors responsible for the system of roles described throughout the rest of this document. 273 | 274 | [[roles-maintainer-issue]] 275 | === Issue 276 | 277 | {role}/28[bisq-network/roles#28] 278 | 279 | [[roles-maintainer-team]] 280 | === Team 281 | 282 | {gh-team}/roles-maintainers[@bisq-network/roles-maintainers] 283 | 284 | [[roles-maintainer-duties]] 285 | === Duties 286 | 287 | * Follow and enforce the roles <> detailed above. 288 | * <> monthly on the Roles Maintainer <>. 289 | * <> changes to roles <>. 290 | * <> in the `#roles` Keybase channel. 291 | 292 | [[roles-maintainer-rights]] 293 | === Rights 294 | 295 | * Write access to the {gh-org}/roles[bisq-network/roles] repository. 296 | -------------------------------------------------------------------------------- /secure-wallet.adoc: -------------------------------------------------------------------------------- 1 | = Wallet Info and Security 2 | :imagesdir: images 3 | :!figure-caption: 4 | 5 | Bisq is a non-custodial exchange, which means you retain control of your funds. That also means you're in charge of securing your funds. 6 | 7 | This doc covers Bisq wallet basics and how you can secure your Bisq wallet by (1) encrypting it and (2) writing down its seed words so you can restore it later. 8 | 9 | == Wallet Info 10 | 11 | Bisq's built-in Bitcoin wallet is based on https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki[BIP 44^]. BTC wallets have a `m/44'/0'/0'` https://en.bitcoin.it/wiki/BIP_0044[derivation path^] and BSQ wallets have a `m/44'/142'/0'` derivation path. 12 | 13 | The same seed phrase is used for BTC and BSQ wallets. 14 | 15 | == Security 16 | 17 | === Encrypt your wallet 18 | 19 | Before setting a password, your Bisq wallet files are stored on your hard drive unencrypted. That means anyone who gains access to your computer (whether by physically stealing it or by hacking it remotely) can gain access to your private keys and take your bitcoin. 20 | 21 | Setting a password encrypts your Bisq wallet files so they're useless to anyone without the password. 22 | 23 | To set a password, go to the `Wallet password` section of the `Account` screen and enter a password. 24 | 25 | .Set a password to encrypt your Bisq wallet. 26 | image::set-password.png[Set a password to encrypt your Bisq wallet] 27 | 28 | === Write down your seed words 29 | 30 | Now that you've set a password, it's time to write down your wallet's seed words. Go to the `Wallet seed` section of the `Account` screen and *_write down_* the words you see in the `Wallet seed words` field along with the `Wallet date`. Wallet date is required by bitcoinj, which is the library Bisq uses to interact with the Bitcoin network. 31 | 32 | IMPORTANT: You should _actually_ write down your seed words and wallet date using pen and paper. Saving them on your computer, even if you do so in a secure password manager, makes it _possible_ for a hacker to obtain them through sneaky schemes like keylogging. Going low-tech with pen and paper eliminates all such digital attack vectors. 33 | 34 | With just your wallet's seed words and date, you can restore your Bisq wallet and all its BTC and BSQ into a new Bisq wallet if you ever need to. If you lose your wallet's seed words and date, you won't be able to restore your wallet, and all funds in it are lost forever. So make sure you keep that paper safe! 35 | 36 | .Write down your Bisq wallet's seed words & wallet date. 37 | image::seed-words.png[Write down your Bisq wallet's seed words] 38 | 39 | With your wallet encrypted and your seed words written down, the bitcoin in your Bisq wallet is much more secure. 40 | 41 | == Restoring from seed 42 | 43 | [WARNING] 44 | ==== 45 | Your seed words can restore your wallet's BTC and BSQ, but they *do not* restore other Bisq application data such as your payment accounts, open disputes, etc. For that, you need to <>. 46 | 47 | Also note that restoring from seed does not restore <> earned from contributing to Bisq. 48 | ==== 49 | 50 | **Restoring from seed is intended as an emergency measure**, to be used if you can't get your funds back any other way. We highly recommend trying <> to solve common wallet issues first. 51 | 52 | If your goal is to transfer BTC or BSQ, it's best to send the funds to a new address with a transaction. This is also better for usability, as wallets with lots of transactions can cause Bisq to get laggy over time. 53 | 54 | **You should only restore from seed into a new Bisq wallet**. You could restore BTC funds to an external wallet like Electrum, but restoring BSQ on a non-Bisq wallet is virtually guaranteed to fail given the complex nature of BSQ transactions (<>). 55 | 56 | NOTE: If you do restore from seed on Bisq and still see a zero balance for BTC or BSQ, make sure to wait until the program is done syncing with the Bitcoin network (when done, the green bar on the bottom right labeled `Synchronizing with Bitcoin Mainnet (using Tor) / Synchronizing DAO` will go away). 57 | -------------------------------------------------------------------------------- /user-dao-intro.adoc: -------------------------------------------------------------------------------- 1 | = Introduction to the Bisq DAO 2 | :imagesdir: ./images 3 | :!figure-caption: 4 | 5 | Just as the Bisq exchange is decentralized and censorship-resistant, so is its governance model—and the Bisq DAO and BSQ token are the tools that make it possible. 6 | 7 | The Bisq founders realized that decentralized software—no matter how technically robust—is no good if it's still controlled by a single entity. All the software's technical strength would be worthless if the whole project could be ruined by attacking the single entity that runs it. 8 | 9 | Thus the need for decentralizing the resources in charge of running Bisq itself. These resources cannot be organized in the form of a company, a nonprofit, or any other traditional organization because a single entity would be a single point of failure. But what to do? How can a project do anything useful without becoming an organization with some kind of structure? How can strategy be determined? How can resources be allocated? How can work get done? How can revenue be earned, and how can it be distributed? 10 | 11 | The Bisq project needed infrastructure to provide these functions, and the Bisq DAO is its solution. 12 | 13 | video::pNvOZlIDYEQ[youtube] 14 | 15 | == What is a DAO? 16 | 17 | Conventional entities such as for-profit and non-profit corporations must be sanctioned by the state: they are legal entities registered in particular jurisdictions. No matter how big or small or virtuous or innovative they are, they cannot operate without state approval. In return for this approval, the entity is endowed with rights (e.g., limited liability) and responsibilities (e.g., taxes). 18 | 19 | A **decentralized autonomous organization** (DAO) is just a generic term for a governance model sanctioned by software: code defines conventions for governing the project irrespective of the stance of the state. 20 | 21 | NOTE: We say a DAO's governance model must be _sanctioned_ by software, not necessarily _controlled_ by software. The Bisq DAO, for example, is not controlled by software: software merely provides a framework for the people involved with the Bisq project to (collectively) manage the software itself. The Bisq DAO operates on the idea that **code is not law**. Code is written by humans to provide a service to other humans, so it should be accountable to humans too. 22 | 23 | The universe of DAOs is diverse. Just as companies come in many shapes and sizes, and some companies are scammy, fraudulent, or just poorly managed—that's no reason to assume all companies are the same way. It's the same with DAOs: some DAOs haven't worked out so well, but others might turn out differently. 24 | 25 | 26 | == The Bisq DAO 27 | 28 | The Bisq DAO forgoes a system where governance is _dictated_ by the rigid rules of software in favor of a self-contained economy where governance is _guided_ by software but ultimately determined by the collective, subjective judgments of its community. 29 | 30 | It achieves this by introducing a unit of value called the **BSQ token** that enables Bisq stakeholders—contributors, traders, or anyone who owns BSQ—to make subjective value judgments. This token underlies all actions in the DAO. 31 | 32 | === BSQ Token 33 | 34 | A BSQ token is a **colored coin** on the Bitcoin blockchain. More plainly, a BSQ token is merely a few satoshis with some additional properties that identify it as BSQ in Bisq software. Outside Bisq, a BSQ token just looks like a few satoshis. But on Bisq, the additional properties have the following results: 35 | 36 | 1. the satoshis take on the market value of a BSQ token 37 | 2. the owner of the satoshis is endowed with power to participate in various Bisq governance functions 38 | 39 | See it for yourself: here's a https://blockstream.info/tx/0243f99c848de4f53cb29157d10bf1cdbfcf4219f84e9997dd3cac9244ab7242/[BSQ transaction on an ordinary block explorer^], and here's https://explorer.bisq.network/tx.html?tx=0243f99c848de4f53cb29157d10bf1cdbfcf4219f84e9997dd3cac9244ab7242[that same transaction on a BSQ block explorer^]. 40 | 41 | The value of a BSQ token is determined by the market as stakeholders buy and sell tokens to perform various functions in the DAO. Because BSQ tokens are only recognized by Bisq software, BSQ trading can only happen in Bisq software. 42 | 43 | NOTE: The BSQ token is not associated with any kind of initial coin offering (ICO) or capital-raising initiative. It's merely a tool to decentralize the governance of the already-functional Bisq exchange service. As of December 2018, Bisq has facilitated over 19,000 trades without major incident since it went into production in April 2016. 44 | 45 | You can learn more about colored coins https://www.youtube.com/watch?v=68_DU1c0Cac[here in this interview^]. Technical details of BSQ tokens are available <>. 46 | 47 | === Overview 48 | 49 | Here's a graphical overview of how the DAO works at a high level: 50 | 51 | image::user-dao-diagram.png[Overview of the Bisq DAO] 52 | 53 | Let's observe some of the dynamics of this system: 54 | 55 | * Contributors _maintain_ Bisq through valuable work 56 | * Traders _use_ Bisq to buy and sell bitcoin and other cryptocurrencies 57 | * Contributors _earn_ BSQ tokens when their compensation requests are approved through voting 58 | * Traders _buy_ BSQ tokens in order to pay lower trading fees 59 | * Stakeholders _vote_ on compensation requests 60 | * Contributors can _lock_ a bond in BSQ to ensure integrity in high-trust roles 61 | 62 | Now let's see how these dynamics enable the Bisq DAO to provide 3 core governance functions without any central points of authority. 63 | 64 | === Earn and distribute revenue 65 | 66 | Every project needs to be financially sustainable to fund ongoing operations and development. But traditional means of handling revenue and revenue distribution are necessarily centralized—any receiving address or account must be owned by one person, or a small group; determining how much a person should be paid must be determined by one person, or a small group; etc. 67 | 68 | ===== Contributors produce, creating BSQ 69 | In the Bisq DAO, trading fees are collected from traders and distributed to contributors, but there is no central authority to do this. Here's how it works: after a Bisq contributor does work, they file a **compensation request** in the DAO with a description of what they did and how much BSQ they want in return. Then, stakeholders (who are other contributors, traders, and anyone else with BSQ) vote for/against the request. If the request is approved, the contributor is issued _new_ BSQ in the amount they requested and **BSQ supply is increased**. 70 | 71 | [NOTE] 72 | .Where does new BSQ actually come from? 73 | ==== 74 | Recall that a BSQ token is merely colored bitcoin. When a contributor makes their compensation request in the DAO, they must also include the tiny amount of bitcoin to be 'colored' as BSQ (<> requires 100 satoshis). So if a contributor requests 1,000 BSQ, they will need to include 100 * 1,000 = 100,000 satoshis with their compensation request—just about 10 USD at a rate of 10,000 USD/BTC. 75 | 76 | If their request is approved, those satoshis are 'colored' and recognized as 1,000 valid BSQ tokens on Bisq. Assuming a BSQ market value of 1 USD (exact value will fluctuate), the contributor will have been granted 1,000 USD worth of BSQ for a negligible cost of 10 USD. 77 | ==== 78 | 79 | ===== Traders consume, burning BSQ 80 | Then, a trader looking for lower trading fees can buy those BSQ tokens from a contributor. When they buy BSQ tokens for BTC, the contributor is paid for their work, and the value transfer from producer to consumer is complete! When a trader pays trading fees with BSQ, those BSQ tokens are _burned_ or "decolored" and **BSQ supply is decreased**. This process of creating and destroying BSQ tokens enables a sort of https://docs.bisq.network/dao/phase-zero.html#how-bsq-decentralizes-compensation-and-enables-monetary-policy[monetary policy^] controlled by Bisq stakeholders and traders. 81 | 82 | In this way, there is no need for a central entity to collect and distribute revenue: the BSQ token enables a transfer of value from producer to consumer without any single entity controlling any aspect of the decision-making or distribution process. 83 | 84 | NOTE: The Bisq DAO does not _require_ traders to use BSQ for trading fees. They're free to pay trading fees directly with BTC, but they will pay higher rates than if they bought BSQ with BTC and paid with BSQ instead. 85 | 86 | [sidebar] 87 | .Note on BTC revenues 88 | -- 89 | In the past, before the Bisq DAO launch and before the integration of Bisq's new trade protocol, trading fees were only collected in BTC and only went to arbitrators. There was no mechanism to distribute them to other contributors. The DAO solves this distribution problem with BSQ through the process outlined above. 90 | 91 | But since traders can still pay trading fees with BTC, where do those BTC fees go? 92 | 93 | BTC fees go to a bitcoin "donation" address held by a https://github.com/bisq-network/roles/issues/80[bonded contributor^], who uses the BTC to buy BSQ on a regular basis to distribute the BTC fees to stakeholders, and the BSQ obtained https://github.com/bisq-network/proposals/issues/55[is burned^]. 94 | -- 95 | 96 | === Determine strategy 97 | 98 | Another point of centralization in traditional organizations is with strategy. How can a project determine strategy without some form of designated leadership: an executive, manager, or leader to give direction and allocate resources? 99 | 100 | The Bisq DAO beats this tradition with collective decision-making on strategy and other matters through **weighted voting** based on BSQ stake. 101 | 102 | Here's how it works: any stakeholder can make a proposal in the DAO. It can be anything: a change in a trading parameter, a new bonded role, or even something more generic like an adjustment of overall project strategy. Stakeholders vote on the proposal, and their voting weight is based on BSQ stake, through a combination of two metrics: 103 | 104 | 1. amount of BSQ committed to a particular vote 105 | 2. amount of BSQ earned over time through contributions 106 | 107 | Taking both metrics into account discourages deep-pocketed whales from suddenly seizing control of the project, while still valuing dedicated stakeholders with consistent contributions over time. It brings about a **strict meritocracy** in which people need to somehow _buy in_ to the Bisq project in order to take part in its governance, and the more significant their stake, the stronger their voice. 108 | 109 | In this way, there is no need to rely on a single leadership team for direction: the community collectively manages itself. 110 | 111 | === Ensure honesty in high-trust roles 112 | 113 | Despite the Bisq project's attempts to resist concentrating control as much as possible, it's impossible to avoid in some places. Domain name owners, social account admins, mediators, various node operators: these are all roles that must exist, but necessarily retain significant control and require a high degree of trust. 114 | 115 | Part of the benefit of a centralized team of thoroughly-vetted people reliant on a paycheck, as is the case in most companies, is that the risk of trusting people with significant responsibility is lower: they have a lot to lose if the company finds they have violated their integrity and engaged in foul play. 116 | 117 | This dynamic can be reproduced—at least partly—in a project without a central authority through **bonding**. The concept is simple enough: create skin in the game. Require that a person interested in taking on a high-trust role post a bond that's high enough to discourage them from engaging in foul play. 118 | 119 | But what happens if that person goes rogue? In a project without central authority, who decides when they've crossed the line, and what their fate should be? 120 | 121 | As with strategy and compensation, the community decides through voting. Anyone who suspects foul play can make a case for confiscating a bond with a new proposal, and stakeholders vote to determine an outcome. 122 | 123 | NOTE: Confiscating a bond is a harsh penalty which should not be taken lightly. Therefore, the Bisq DAO makes confiscation proposals especially hard to approve: they require a quorum of at least 200,000 BSQ and 85% acceptance to pass (instead of the typical >50%). 124 | 125 | In this way, the risk that people in high-trust roles misbehave is minimized, and the community has access to a responsible mechanism for handling such a scenario in cases that warrant it. 126 | 127 | == Learn more and stay in touch 128 | 129 | To learn more about the Bisq DAO, please see: 130 | 131 | * <>, a doc which offers practical details on the workings of the DAO, along with high-level technical details. 132 | * <>, along with technical details of BSQ tokens, this doc shows example transactions for several DAO functions. 133 | * <>, a doc which offers a more comprehensive overview of Bisq and the Bisq DAO. 134 | * https://www.youtube.com/playlist?list=PLFH5SztL5cYOLdYJj3nQ6-DekbjMTVhCS[Bisq DAO Basics^], a YouTube video series that covers foundational concepts underlying the DAO such as bitcoin transactions, colored coins, etc. 135 | 136 | See more resources <>. Feel free to get in touch with us on https://twitter.com/bisq_network[Twitter^], https://keybase.io/team/bisq[Keybase^], or https://bisq.community/[the forum^]. 137 | 138 | 139 | == Improve this doc 140 | 141 | Find a typo or have other suggestions for improvement? Please https://github.com/bisq-network/bisq-docs/blob/master/{docname}{docfilesuffix}[edit this doc] or https://github.com/bisq-network/bisq-docs/issues/new?title=Improvement+suggestion+for+{docname}{docfilesuffix}[report an issue]. 142 | --------------------------------------------------------------------------------