diff --git a/getting-started-dao.adoc b/getting-started-dao.adoc index 3a9bf8b..d3d17a7 100644 --- a/getting-started-dao.adoc +++ b/getting-started-dao.adoc @@ -1,110 +1,50 @@ -= Getting Started with the Bisq DAO += User Guide: Bisq DAO for Contributors :imagesdir: ./images :!figure-caption: -This guide will show you how to use the Bisq DAO for governance by walking you through the process of making a proposal and voting. +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. -_This document became outdated with the launch of the Bisq DAO on mainnet, and while it will be updated soon, keep in mind the basic processes of making proposals and voting remain largely the same._ - -Specifically, we will walk through one voting cycle. Voting is a crucial duty within 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. +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. For a brief overview of how the Bisq DAO works, see our <> doc. -[IMPORTANT] -.Before you get started, please note the following: -==== - -* **This guide assumes you have Bisq v0.9.1 or later installed**. If not, you can get it from https://bisq.network/downloads/[the Bisq downloads page^]. - -* **All references to BTC and BSQ in this guide are for test values**. You should _not_ be working with real BTC at any point during this guide. -==== - -Let's begin! - -[sidebar] -.Quick note on testing --- -The launch of the DAO is a critical step for the Bisq Network. Rigorous testing and feedback from a wide user base is crucial, and as with all valuable contributions to Bisq, we're awarding BSQ to meaningful testing feedback. - -Upon completing a testing cycle, as outlined in this doc, we invite you to take part in the following: - -* **Complete a survey**. https://docs.google.com/forms/d/e/1FAIpQLSdS4YRE9Eox3bvuo4oSJJQCm5Yy54ZclKC_ThUt702PeU4rxw/viewform[This one^]. It's short, only 4 questions. _Award: 20 BSQ_. -* **Create a meaningful GitHub issue**. Something that will help developers improve the software and user experience. Please create issues in https://github.com/bisq-network/bisq[the main Bisq repository^]. _Award: 50 BSQ_. -* **Find an advanced technical flaw**. Find consensus bugs, data inconsistencies, or some other major bug? Let us know. More details https://bisq.community/t/how-to-explore-the-dao-on-testnet/6692[here^]. _Award: varies; up to 10,000 BSQ_. - -If you do take part in any of the items above, don't forget to <> at the end of the month! --- - -[[switch-to-testnet-mode]] -== Switch to dao-regtest mode - -NOTE: Issues on the main Bitcoin testnet made it unusable for Bisq DAO testing, so _dao-regtest_ refers to a regtest network maintained by Bisq contributors specifically for DAO testing. - -The Bisq DAO is only live in dao-regtest mode right now, so to try it out, you'll need to run Bisq in dao-regtest mode. - -There are 2 ways to enable it: - -==== Option A: Through the command-line - -If you're comfortable with the command-line, you might prefer this method, as it allows you to run a dao-regtest version of Bisq alongside mainnet Bisq (so you don't lose access to any open trades/disputes while testing). - -Just run the Bisq executable with the `--baseCurrencyNetwork=BTC_DAO_REGTEST` flag. Default locations for the Bisq executable are: - -* **Windows**: "C:\Users\\AppData\Local\Bisq\Bisq.exe" -* **Mac**: /Applications/Bisq.app/Contents/MacOS/Bisq -* **Linux**: /opt/Bisq/Bisq - -==== Option B: Through the graphical interface - -Pick the `Bitcoin DAO Regtest` option in the drop-down in the `General preferences` section of the `Settings` screen. +== Obtain BSQ -Bisq maintains completely separate data directories for different currency networks, so it will generate a whole new directory when you restart Bisq in dao-regtest mode for the first time. When you switch back to mainnet, your mainnet configuration will be reloaded, untouched from your time on dao-regtest. +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. -[WARNING] -.Beware of open offers and open disputes! -==== -Because Bisq runs from a totally different data directory in dao-regtest mode, it won't know anything about open offers and open disputes from mainnet. So if you have any such open items, be aware that you won't get updates on them until you switch back to mainnet mode. +NOTE: You can learn more about the BSQ token, how it's issued, and more in our <> and/or our <>. -To avoid this issue, consider running from the command-line with the instructions above. -==== +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. -Go ahead and restart Bisq when prompted. Voilà—you should be in dao-regtest mode. You'll know because the window's title bar should include the text `[Bitcoin DAO Regtest]`. +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. -.Switch to dao-regtest from the Settings screen. -image::switch-testnet.png[Switch to dao-regtest] +Simply make or take an offer you like: -[[acquire-some-bsq]] -== Request BSQ and BTC for testing +.BSQ buy offers. +image::bsq-buy-offers.png[BSQ buy offers] -As we covered in the <> doc, virtually all actions in the Bisq DAO require BSQ tokens. So let's get some! +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. -To get test BSQ and BTC, simply ask for some https://bisq.network/slack-invite[on Slack^] and a contributor will send you some. Don't forget to include your addresses. +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). -==== Get your BTC address -Go to the `Funds` screen. On the `Receive funds` tab, you'll see your BTC addresses. Pick one, preferably an unused one. - -==== Get your BSQ address -Go to the `DAO` screen, navigate to the `BSQ Wallet` tab. In the `Receive` section, you'll see an address: - -.Get your BSQ wallet address. -image::get-bsq-address.png[Get your BSQ address] +//See more details on how to buy BSQ in <>. == Participate in a voting cycle -Now that you've got some BSQ, let's use it. +As we cover in our <> doc, the BSQ token has several functions within Bisq. -There's a lot you'll be able to do with BSQ when the DAO goes live on mainnet (like, for example, getting a 90% discount on trading fees by paying for trades with BSQ instead of BTC). +Here, we will focus on governance: making proposals and voting on proposals to adjust various aspects of Bisq. -For now, we'll use it to test Bisq's governance mechanism: making proposals and voting on proposals to change various aspects of Bisq. +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,510 blocks (about 1 month on average). -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,380 blocks (about 1 month on average). Here are the 4 phases: +Here are the 4 phases: 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. 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. 3. **Vote reveal phase**, in which each stakeholder sends the decryption key for their vote. 4. **Vote result phase**, in which vote results are calculated and BSQ is issued accordingly. -For testing, voting cycles are shortened to 979 blocks (just under 7 days), and each phase is shortened proportionally. You can see exact timeframes on the `Dashboard` section of the `Governance` tab on the `DAO` screen. +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. .Voting cycle overview. image::voting-cycle-overview.png[Voting cycle overview] @@ -113,98 +53,119 @@ Let's begin by making a proposal. === 1. Make a proposal -NOTE: To make a proposal for the current voting cycle, the voting cycle needs to be in the proposal phase. If it's in the blind voting phase, you can skip this section and <<2-vote-on-proposals, vote on current proposals>>. If it's beyond both these phases, you'll need to wait to participate until the next voting cycle starts. +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. -In the `Make proposal` section of the `Governance` tab of the `DAO` screen, you'll find a form to make a new proposal. Simply fill the form and hit `Make proposal`. +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`. -We'll make a proposal to change a parameter, but feel free to make another type of proposal: +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. -.Make a proposal. -image::make-test-dao-proposal.png[Make a proposal] +We'll make a general proposal here, for demonstration: -Couple things to note: +.Make a proposal. +image::make-dao-proposal.png[Make a proposal] -* Information you're asked to provide will vary based on the type of proposal you're making. -* In most cases, you'll need to provide a link with more information on your proposal. Since these proposals are not real, please don't make new GitHub issues—just link to one that already exists. -* There's a 2 BSQ fee to make a proposal to discourage spam. +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 <>. -Once you're done making a proposal, you can sit back and relax until voting starts. +When you're done, you can sit back and relax until voting starts. -=== 2. Vote on proposals +=== 2a. Vote on proposals [.float-group] -- [.right.text-center] -.Cast vote on a proposal. -image::vote-proposal.png[Cast vote on proposal,400,400] +.Cast vote on proposals. +image::vote-proposal.png[Cast vote on proposals,400,400] -Once the period to make proposals is over, it's time to vote. As long as you have some BSQ, you can vote—it doesn't matter if you submitted a proposal or not. +Once the period to make proposals is over, it's time to vote. You can see all proposals in the current voting cycle in the `Browse open proposals` section of the `Governance` tab on the `DAO` screen. -Click through each proposal to see more details, and then vote on the proposals you want—you can vote for the ones you like (ideally, the ones you know intimately and have a strong opinion about). +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. -- +=== 2b. Submit votes + +When you're done selecting your votes, don't forget to actually submit your votes! It can be easy to miss this. + [.float-group] -- [.left.text-center] .Select voting weight and submit all votes. -image::vote-submit.png[Select voting weight ad submit all votes,400,400] +image::vote-submit.png[Select voting weight and submit all votes,400,400] -When you're done casting your votes, make sure you actually submit your votes by clicking the `Vote on all proposals` button at the bottom of the screen. +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. -To submit your votes, you'll need to specify a BSQ amount to use for **voting weight**. The more BSQ you include in your vote, the more weight the vote carries. This BSQ cannot be traded or otherwise transferred for the remainder of the voting cycle, or your vote will be rendered invalid. It will be released for you to use again as soon as the voting cycle has finished. +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. -This is why, as you see in the screenshot to the left, we use most (but not all) of our BSQ for the voting weight—we left some BSQ available for spending in case we need it for other purposes during the voting cycle. +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. -- `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. -For an overview of voting weight, see <> of our Introduction to the Bisq DAO doc. +NOTE: For more details on how voting weight is determined, see <> of our User Reference doc. + +Once you've entered a voting stake, go ahead and click the `Vote on all proposals` button at the bottom of the screen. === 3. Reveal your vote +[.float-group] +-- + 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**. -IMPORTANT: Bisq will publish the transaction automatically when it's online, so you don't have to actually do anything, but you can check the https://explorer.bisq.network/[BSQ block explorer^] to be sure the transaction was published. More details <<#explore-a-bsq-block-explorer,below>>. +[.right.text-center] +.Vote reveal pop-up. +image::vote-reveal-popup.png[Vote reveal pop-up.,400,400] + +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. -This transaction includes the key to decrypt your vote from the last 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 <>. +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 <>. -Don't forget this step! If your vote reveal transaction is not published, your vote won't be decrypted, and it won't be counted. +Don't forget this step! If your vote reveal transaction is not published, your vote cannot be decrypted, and so it cannot be counted. + +-- === 4. Get vote results -Once the vote reveal phase is over, results are published and the next voting cycle starts. You can see results on the `Vote results` section of the `Governance` tab of the `DAO` screen. +Once the vote reveal phase is over, results are calculated and the next voting cycle starts. -.See voting results. -image::dao-vote-results.png[See voting results] +You can see results of the last voting cycle the `Vote results` section of the `Governance` tab of the `DAO` screen. -As you can see, our proposal was accepted. Hopefully you have similar luck! +.See voting results. +image::dao-vote-results.png[See voting results.] 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. -That's it—you've now participated in a full voting cycle of the Bisq DAO, the upcoming decentralized governance mechanism for the Bisq exchange. Bravo! +That's it—you've now participated in a full voting cycle of the Bisq DAO, the decentralized governance mechanism for the Bisq exchange. -NOTE: If you could, please fill out our https://docs.google.com/forms/d/e/1FAIpQLSdS4YRE9Eox3bvuo4oSJJQCm5Yy54ZclKC_ThUt702PeU4rxw/viewform[DAO testing survey^]. It's very helpful to us! +Bravo! == Explore a BSQ block explorer -Since BSQ is just bitcoin, you can see BSQ transactions on any bitcoin block explorer. But because these bitcoins are colored, ordinary bitcoin block explorers can't recognize which bitcoin transactions are also BSQ transactions. +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. So there's a https://explorer.bisq.network/[BSQ block explorer^]. Whenever you do a BSQ transaction, you can see it there. -Here's a screenshot of the past few BSQ transactions as of mid-December 2018. You'll notice that this block explorer recognizes the various transaction properties that make valid BSQ transactions, and it labels them accordingly: +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. + +You'll notice that this block explorer recognizes the various transaction properties that make valid BSQ transactions, and it labels them accordingly. + +Here's a snapshot of the latest transactions on the BSQ explorer during a voting phase: .Some BSQ transactions on the https://explorer.bisq.network[BSQ block explorer^]. -image::bsq-block-explorer.png[Some recent BSQ transactions] +image::bsq-block-explorer-voting.png[Some recent BSQ transactions] + +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. == Next steps -At the moment, the Bisq DAO is being tested thoroughly. If you'd like to help, there are bounties! https://bisq.community/t/how-to-explore-the-dao-on-testnet/6692[See more details here^]. +We covered the Bisq DAO here in a very practical way: just the steps you need to follow to make a proposal and vote. + +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 <>. -Otherwise, check out our <> and our two video series: one that's https://www.youtube.com/playlist?list=PLFH5SztL5cYPAXWFz-IMB4dBZ0MEZEG_e[quick and to-the-point^] and another that's https://www.youtube.com/playlist?list=PLFH5SztL5cYOLdYJj3nQ6-DekbjMTVhCS[more extensive^]. +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. == Get help and stay in touch diff --git a/images/add-new-bsq-account.png b/images/add-new-bsq-account.png index c31fe4b..a219706 100644 Binary files a/images/add-new-bsq-account.png and b/images/add-new-bsq-account.png differ diff --git a/images/bsq-block-explorer-trading.png b/images/bsq-block-explorer-trading.png new file mode 100644 index 0000000..3c87be9 Binary files /dev/null and b/images/bsq-block-explorer-trading.png differ diff --git a/images/bsq-block-explorer-voting.png b/images/bsq-block-explorer-voting.png new file mode 100644 index 0000000..0d7d805 Binary files /dev/null and b/images/bsq-block-explorer-voting.png differ diff --git a/images/bsq-block-explorer.png b/images/bsq-block-explorer.png deleted file mode 100644 index bc050cc..0000000 Binary files a/images/bsq-block-explorer.png and /dev/null differ diff --git a/images/bsq-buy-offers.png b/images/bsq-buy-offers.png new file mode 100644 index 0000000..7ed58c2 Binary files /dev/null and b/images/bsq-buy-offers.png differ diff --git a/images/dao-vote-results.png b/images/dao-vote-results.png index d98f282..6dfdc3f 100644 Binary files a/images/dao-vote-results.png and b/images/dao-vote-results.png differ diff --git a/images/make-dao-proposal.png b/images/make-dao-proposal.png new file mode 100644 index 0000000..738a40c Binary files /dev/null and b/images/make-dao-proposal.png differ diff --git a/images/make-test-dao-proposal.png b/images/make-test-dao-proposal.png deleted file mode 100644 index cf1eb1d..0000000 Binary files a/images/make-test-dao-proposal.png and /dev/null differ diff --git a/images/vote-proposal.png b/images/vote-proposal.png index e7cfd82..f4c8564 100644 Binary files a/images/vote-proposal.png and b/images/vote-proposal.png differ diff --git a/images/vote-reveal-popup.png b/images/vote-reveal-popup.png new file mode 100644 index 0000000..b0d8831 Binary files /dev/null and b/images/vote-reveal-popup.png differ diff --git a/images/voting-cycle-overview.png b/images/voting-cycle-overview.png index 462fa14..1a1fd3f 100644 Binary files a/images/voting-cycle-overview.png and b/images/voting-cycle-overview.png differ diff --git a/index.adoc b/index.adoc index d742852..5d3ad92 100644 --- a/index.adoc +++ b/index.adoc @@ -52,7 +52,7 @@ image::quick-link-4.png[alt=Make a Compensation Request,width=200,role=quick-lin === Bisq DAO: Governing Bisq * <> — _Learn how the DAO enables Bisq's decentralized governance model_ - * <> — _Trade, vote, and govern Bisq through the DAO with BSQ_ + * <> — _Govern Bisq through the DAO by making proposals and voting_ * <> — _Practical details on using the DAO, along with a brief technical overview_ * <> — _Technical details of DAO functions and transactions_