diff --git a/exchange/howto/images/multisig-payout-tool.png b/exchange/howto/images/multisig-payout-tool.png deleted file mode 100644 index 0242491..0000000 Binary files a/exchange/howto/images/multisig-payout-tool.png and /dev/null differ diff --git a/exchange/howto/list-asset.adoc b/exchange/howto/list-asset.adoc index 8ba539a..f4e37fc 100644 --- a/exchange/howto/list-asset.adoc +++ b/exchange/howto/list-asset.adoc @@ -35,7 +35,7 @@ A Bisq arbitrator must be able to look up transactions in the asset's block expl == Instructions -IMPORTANT: Each of the steps described below deal with code in the https://github.com/bisq-network/bisq-core repository. You will need to fork this repository, make the specified changes, and then submit those changes as a SINGLE COMMIT within a SINGLE PULL REQUEST. Please DO NOT issue several pull requests by attempting to modify the sources one by one via the GitHub web UI. You need to have a competent developer make these changes and actually run the tests. *To be extra clear:* If you are unfamiliar with Java, don't know what a "pull request" is, or have never created a pull request yourself, please do not attempt to follow the instructions below on your own. +IMPORTANT: Each of the steps described below deal with code in the https://github.com/bisq-network/bisq-assets repository. You will need to fork this repository, make the specified changes, and then submit those changes as a SINGLE COMMIT within a SINGLE PULL REQUEST. Please DO NOT issue several pull requests by attempting to modify the sources one by one via the GitHub web UI. You need to have a competent developer make these changes and actually run the tests. *To be extra clear:* If you are unfamiliar with Java, don't know what a "pull request" is, or have never created a pull request yourself, please do not attempt to follow the instructions below on your own. === Step 1. Implement your asset @@ -43,7 +43,7 @@ IMPORTANT: Each of the steps described below deal with code in the https://githu .The `bisq.asset.Asset` type hierarchy image::images/asset-hierarchy.png[Asset Hierarchy] -All assets listed on the Bisq exchange ultimately implement the https://jitpack.io/com/github/bisq-network/bisq-core/-SNAPSHOT/javadoc/bisq/asset/Asset.html[`bisq.asset.Asset`] interface. Your asset implementation will need to extend the https://jitpack.io/com/github/bisq-network/bisq-core/-SNAPSHOT/javadoc/bisq/asset/Coin.html[`Coin`], https://jitpack.io/com/github/bisq-network/bisq-core/-SNAPSHOT/javadoc/bisq/asset/Token.html[`Token`] or https://jitpack.io/com/github/bisq-network/bisq-core/-SNAPSHOT/javadoc/bisq/asset/Erc20Token.html[`Erc20Token`] subtypes as appropriate. +All assets listed on the Bisq exchange ultimately implement the https://jitpack.io/com/github/bisq-network/bisq-assets/-SNAPSHOT/javadoc/bisq/asset/Asset.html[`bisq.asset.Asset`] interface. Your asset implementation will need to extend the https://jitpack.io/com/github/bisq-network/bisq-assets/-SNAPSHOT/javadoc/bisq/asset/Coin.html[`Coin`], https://jitpack.io/com/github/bisq-network/bisq-assets/-SNAPSHOT/javadoc/bisq/asset/Token.html[`Token`] or https://jitpack.io/com/github/bisq-network/bisq-assets/-SNAPSHOT/javadoc/bisq/asset/Erc20Token.html[`Erc20Token`] subtypes as appropriate. TIP: The links above point to Javadoc for each respective type. Read it! @@ -102,7 +102,7 @@ Date: Wed Aug 1 00:00:00 1979 -0800 === Step 6. Submit your pull request -Your pull request should be submitted against the bisq-network/bisq-core repository's `master` branch. Make sure you do this from a dedicated topic branch in your fork named, for example, `list-foo-asset`. Do not submit your pull request directly from your `master` branch, as this can make things unnecessarily complex if and when there are merge conflicts. +Your pull request should be submitted against the bisq-network/bisq-assets repository's `master` branch. Make sure you do this from a dedicated topic branch in your fork named, for example, `list-foo-asset`. Do not submit your pull request directly from your `master` branch, as this can make things unnecessarily complex if and when there are merge conflicts. Copy and paste the form template below into the description of the pull request and fill it out. @@ -142,4 +142,4 @@ Whenever we ship the next Bisq release, your newly-listed asset will be included === Pull requests that do not conform to the requirements above will be rejected -If your pull request is for any reason incorrect, e.g. code does not compile, tests do not pass, steps have been missed in the instructions, your changes will be ignored and your pull request will be closed. Getting your asset successfully listed is 100% your responsibility. If you follow the instructions, the `bisq-core` maintainers will merge it; if you don't, they won't. It's that simple. +If your pull request is for any reason incorrect, e.g. code does not compile, tests do not pass, steps have been missed in the instructions, your changes will be ignored and your pull request will be closed. Getting your asset successfully listed is 100% your responsibility. If you follow the instructions, the `bisq-assets` maintainers will merge it; if you don't, they won't. It's that simple. diff --git a/exchange/howto/manual-dispute-payout.adoc b/exchange/howto/manual-dispute-payout.adoc index 4a87750..ffabb8b 100644 --- a/exchange/howto/manual-dispute-payout.adoc +++ b/exchange/howto/manual-dispute-payout.adoc @@ -1,184 +1 @@ -= How to issue a manual dispute payout -:toc: - -== Introduction - -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. - -== Arbitrator instructions - -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. - -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 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: - - 1. Re-open both buyer and seller tickets for this trade using `cmd-U` - 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. - -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. - -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. - -=== Step 1. Review dispute details - -In `Support > Aribtrator'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 recieved 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: - -image:images/determine-winner.png[determining who was the winner] - -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. - -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. - -image:images/closing-message.png[closing message] - -Next, click the `Details` button on the dispute ticket, and *take note of the BTC address for both buyer and seller*: - -image:images/buyer-seller-address.png[buyer and seller addresses] - -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: - -image:images/get-pubkey-hex.png[get pubkey hex value] - -Also *take note of the `txFee` value in the contract JSON*, e.g.: - - "txFee": 36000, - -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.: - - 36000/100000000 = 0.00036000 BTC - -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*: - -image:images/p2sh-multisig-output-script.png[P2SH multisig output script] - -=== Step 2. Get arbitrator's public and private key - -*Remove your wallet password* (by following the same steps as found in <> in the trader instructions section). - -*Open the Wallet Data* dialog with `cmd-j` and *check the `Include private keys` checkbox*. - -*Copy the contents of the Wallet Data dialog* and paste it into a text editor. - -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: - - BTC Wallet: - Address entry list: - AddressEntry{offerId='null', context=ARBITRATOR, address=1DBX...} - AddressEntry{offerId='null', context=AVAILABLE, address=1HN2...} - -Now search the file for the first match for the string `addr:1DBX...`. You should find a section that looks like the following: - - Key to watch: xpub... - addr:1ABC... hash160:f778... - DeterministicKey{pub HEX=02ff..., priv HEX=dfc8..., ...} - addr:1DBX... hash160:760d... - DeterministicKey{pub HEX=039d..., priv HEX=929d..., ...} - -*Note both the `pub HEX` and `priv HEX` values for the `addr:1DBX...` entry*, which should be the second entry in the list. - -You can now *reset your wallet password*. - -=== Step 3. Get trader's private key - -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`. - -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. - -When you have the trader's private key, move on to the next step. - -=== Step 4. Issue the manual dispute payout - -Now that you have all the necessary information, you can *open the Emergency multi-sig payout tool* by clicking `alt-g` in the dispute view: - -image:images/multisig-payout-tool.png[Emergency multi-sig payout tool] - -NOTE: Several values are pre-filled in the payout tool. They are a left-over from testing in an earlier version of Bisq. *You should erase these pre-filled values and replace them with the ones you have collected in the steps above*. - -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. - -buyerPayoutAmount:: The amount in BTC that the buyer should be paid out, as noted above, e.g. `0.03` - -sellerPayoutAmount:: The amount in BTC the seller should be paid out, e.g. `0.0662` - -arbitratorPayoutAmount:: This value should always be `0`, as we no longer issue payouts to arbitrators - -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 - -buyerAddressString:: The buyer's bitcoin address - -sellerAddressString:: The seller's bitcoin address - -arbitratorAddressString:: The arbitrator's bitcoin address - -buyerPrivateKeyAsHex:: The buyer's private key (leave empty if buyer was not the winner) - -sellerPrivateKeyAsHex:: The seller's private key (leave empty if seller was not the winner) - -arbitratorPrivateKeyAsHex:: The arbitrator's private key - -buyerPubKeyAsHex:: The buyer's public key - -sellerPubKeyAsHex:: The seller's public key - -arbitratorPubKeyAsHex:: The arbitrator's public key - -P2SHMultiSigOutputScript:: The P2SH multi-sig output script hex value as copied from the block explorer - -When all values have been entered (and double-checked!), click `Sign and publish transaction` to issue the payout. - -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*. - - -== Trader instructions - -[WARNING] -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. - -=== Step 1. Get your public key from your arbitrator - -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. - -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. - -=== Step 2. Remove your wallet password [[remove-password]] - -Removing your wallet password is necessary in order to get the unencrypted value of your corresponding private key in the next step. - -Go to `Account > Wallet Password`, enter your password and click the `Remove password` button: - -image:images/password-active.png[wallet password active] - -When your wallet password has been removed, you should see the following: - -image:images/password-removed.png[wallet password removed] - -You can now move on to the next step. - -=== Step 3: Send your private key to your arbitrator - -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: - -image:images/wallet-data.png[wallet data dialog] - -At the bottom of the dialog, *check the box that reads `Include private keys`*: - -image:images/include-private-keys.png[include private keys] - -Then *click `Copy to clipboard`*. - -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. - -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. - -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*. - -Close the text editor. When prompted, *do not save the file*. - -Back in your Bisq client, *send your private key to your arbitrator* by pasting it into the support ticket chat window. - -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. - -=== Step 4: Reset your wallet password - -The final step is to reset your wallet password. - -Go to `Account > Wallet Password`, enter and confirm your password and click `Set password`. +This document has moved <<../../manual-dispute-payout#, here>>. diff --git a/getting-started.adoc b/getting-started.adoc index 9aab726..d36aa31 100644 --- a/getting-started.adoc +++ b/getting-started.adoc @@ -1,3 +1,113 @@ = Getting Started with Bisq +:toc: left +:sectanchors: +:btc_deposit: 0.01 -COMING SOON. Subscribe to https://github.com/bisq-network/bisq-docs/issues/37[bisq-network/bisq-docs#37] for updates. +Bisq is built on some https://bisq.network/philosophy/[serious principles^] and some https://github.com/bisq-network[seriously impressive code^], but it's surprisingly approachable. This guide will help you get up & running quickly. + +Here we're going to assume you want to trade a national currency for bitcoin, because that's Bisq's most common use case. But keep in mind Bisq offers trading for a range of altcoins too—the only constraint is that one side of the trade must always be in bitcoin. + +== Download & install + +To run Bisq, download it from https://bisq.network/downloads/[the Bisq downloads page]. Before installing, it's a good idea to verify the signatures of the downloaded file (https://www.torproject.org/docs/verifying-signatures.html.en[instructions here^]). + +[NOTE] +.Download and install? Why can't I just trade on your website? +==== +Unlike most exchanges, Bisq doesn't run a central server to receive orders. + +Instead, when you place an order on Bisq, it's routed to a global network of people who are also running Bisq's software on their own computers. + +If you want to tap into this network, you've got to run the software too! +==== + +Once the installer is done, go ahead and open Bisq. It'll take a few moments to open as it connects to Tor and Bisq's peer-to-peer trading network. + +[[[Once it does, it'll ask you to set up a wallet...]]] + +[[[discuss first-time application/wallet setup]]] + +When that's done, feel free to have a look around Bisq. You can browse buy offers, sell offers, and tweak your account settings. + +== Configure a national currency account + +Since we're looking to buy bitcoin, let's take a look at the Buy BTC panel. You should see a list of offers. But the orange Buy BTC buttons are all disabled: + + + +That's because we haven't set a way to actually pay for the bitcoin we want to buy. Bisq works with several payment methods, so you can pick one you're most comfortable with. Keep in mind that the one you pick will determine: + +* which offers you can take (e.g., in the picture above Venmo has a handful of outstanding offers...but if you don't want to use Venmo, and if there are no offers for your preferred payment method, you can make your own offer & wait for a taker) +* how quickly a trade can be completed (e.g., a bank transfer will go through quicker than a money order sent by mail; see https://bisq.network/faq/#5[details here^]) + +[NOTE] +.Where is my financial account data stored? +==== +On your computer *only* (i.e., the computer on which Bisq is installed). Only your trading partner (and your arbitrator, if there's a dispute) will ever see your payment details. +==== + +Once you've decided on a payment method, go ahead & configure it on the Account panel by filling in the details: + + + +Once you're done, hit Save New Account and go back to the Buy BTC panel. Offers that use your payment method should now be enabled: + + + +== Fund your Bisq wallet + +We're almost there—last thing: before you buy bitcoin with Bisq, you'll need some bitcoin. + +Huh? + +Here's why: to encourage fair trades, Bisq requires buyers and sellers to post a security deposit. On the buy side, it's {btc_deposit} BTC, along with a tiny bit more to cover the trading fee & mining fees for the transfers. + +[NOTE] +.I'm new to this and have no bitcoin. How can I get bitcoin for the deposit? +==== +You can buy bitcoin on a centralized exchange, but if you're interested in Bisq, chances are you might not want to do that. + +So what can you do? You've got options: friends, family, bitcoin ATMs, bitcoin meetups (commonly called "Satoshi Squares" but there are many others), vouchers, a site like LocalBitcoins.com, or your https://www.youtube.com/watch?v=GbmWGrQjgTA[friendly neighborhood airdrop^] (although you might need to time-travel to find one of these now!). +==== + +To find out exactly how much bitcoin you need to execute a specific trade, choose an offer you like. A new "Take Offer" tab will appear with some deal details. Click "Next step" at the bottom. Accept the disclaimer, and you should see a box that looks like this: + + + +In this case, you'll need 0.012184 BTC to start the trade. Once you've got that bitcoin, you can move it into Bisq's built-in wallet (this is often more convenient, because then Bisq can automatically post your deposit when you enter a trade). Otherwise you'll need to do that yourself (more about that below). + +[[[discuss difference between trade wallet and bisq's built-in wallet? encourage people to use bisq's wallet? maybe as quick admonition?]]] + +Now that you've got enough bitcoin for a deposit, you're ready to trade! + +== Place a trade + +Now for the fun part! Let's actually place a trade. + +[[[--following would be a numbered list with abundant screenshots--]]] + +[[[find an offer]]] + +[[[send deposit to trade wallet--if enough btc in bisq wallet, this is automatic; otherwise, send to trade wallet yourself (need to specify >20 sat/b mining fee?)]]] + +[[[confirm trade]]] + +[[[send payment! this varies...but bisq will guide you. screenshot will show user must wait for 1 confirmation before sending payment]]] + +[[[once you send payment, make sure you tell bisq you've sent it (easy to forget); admonition: good chance to remind users that bisq doesn't actually integrate with fiat payment channels?]]] + +[[[wait for seller to receive]]] + +... + +[[[complete trade]]] + +== Get help + +[[[bisq has presence on many channels...but which are preferred for support? forums, reddit, github...any/all?]]] + +== Stay in touch + +If Bitcoin's motto is "be your own bank" then Bisq's motto is "be your own exchange." It's an exciting concept, it's growing fast, and it's something you'll want to follow. + +[[[encourage follow on twitter, facebook, telegram, youtube, reddit...any/all/others? looks like email list is retired]]] diff --git a/exchange/howto/images/buyer-seller-address.png b/images/buyer-seller-address.png similarity index 100% rename from exchange/howto/images/buyer-seller-address.png rename to images/buyer-seller-address.png diff --git a/exchange/howto/images/closing-message.png b/images/closing-message.png similarity index 100% rename from exchange/howto/images/closing-message.png rename to images/closing-message.png diff --git a/exchange/howto/images/determine-winner.png b/images/determine-winner.png similarity index 100% rename from exchange/howto/images/determine-winner.png rename to images/determine-winner.png diff --git a/exchange/howto/images/get-pubkey-hex.png b/images/get-pubkey-hex.png similarity index 100% rename from exchange/howto/images/get-pubkey-hex.png rename to images/get-pubkey-hex.png diff --git a/exchange/howto/images/include-private-keys.png b/images/include-private-keys.png similarity index 100% rename from exchange/howto/images/include-private-keys.png rename to images/include-private-keys.png diff --git a/images/multisig-payout-tool.png b/images/multisig-payout-tool.png new file mode 100644 index 0000000..a9a0052 Binary files /dev/null and b/images/multisig-payout-tool.png differ diff --git a/exchange/howto/images/p2sh-multisig-output-script.png b/images/p2sh-multisig-output-script.png similarity index 100% rename from exchange/howto/images/p2sh-multisig-output-script.png rename to images/p2sh-multisig-output-script.png diff --git a/exchange/howto/images/password-active.png b/images/password-active.png similarity index 100% rename from exchange/howto/images/password-active.png rename to images/password-active.png diff --git a/exchange/howto/images/password-removed.png b/images/password-removed.png similarity index 100% rename from exchange/howto/images/password-removed.png rename to images/password-removed.png diff --git a/exchange/howto/images/wallet-data.png b/images/wallet-data.png similarity index 100% rename from exchange/howto/images/wallet-data.png rename to images/wallet-data.png diff --git a/index.adoc b/index.adoc index a52aed6..19487ea 100644 --- a/index.adoc +++ b/index.adoc @@ -8,7 +8,7 @@ ** <> ** <> ** <> - ** <> + ** <> ** <> ** <> diff --git a/manual-dispute-payout.adoc b/manual-dispute-payout.adoc new file mode 100644 index 0000000..4481120 --- /dev/null +++ b/manual-dispute-payout.adoc @@ -0,0 +1,207 @@ += How to issue a manual dispute payout +:toc: left +:sectanchors: + +== Introduction + +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. + +== Arbitrator instructions + +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. + +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 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: + + 1. Re-open both buyer and seller tickets for this trade using `cmd-U` + 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. + +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. + +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. + +[TIP] +.Fill this out as you go +==== +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 <>. +---- +depositTxHex: +buyerPayoutAmount: +sellerPayoutAmount: +arbitratorPayoutAmount: +Tx fee: +buyerAddressString: +sellerAddressString: +arbitratorAddressString: +buyerPrivateKeyAsHex: +sellerPrivateKeyAsHex: +arbitratorPrivateKeyAsHex: +buyerPubKeyAsHex: +sellerPubKeyAsHex: +arbitratorPubKeyAsHex: +P2SHMultiSigOutputScript: +---- +==== + +=== Step 1. Review dispute details + +In `Support > Aribtrator'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 recieved 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: + +image:images/determine-winner.png[determining who was the winner] + +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. + +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. + +image:images/closing-message.png[closing message] + +Next, click the `Details` button on the dispute ticket, and *take note of the BTC address for both buyer and seller*: + +image:images/buyer-seller-address.png[buyer and seller addresses] + +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: + +image:images/get-pubkey-hex.png[get pubkey hex value] + +Also *take note of the `txFee` value in the contract JSON*, e.g.: + + "txFee": 36000, + +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.: + + 36000/100000000 = 0.00036000 BTC + +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*: + +image:images/p2sh-multisig-output-script.png[P2SH multisig output script] + +=== Step 2. Get arbitrator's public and private key + +*Remove your wallet password* (by following the same steps as found in <> in the trader instructions section). + +*Open the Wallet Data* dialog with `cmd-j` and *check the `Include private keys` checkbox*. + +*Copy the contents of the Wallet Data dialog* and paste it into a text editor. + +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: + + BTC Wallet: + Address entry list: + AddressEntry{offerId='null', context=ARBITRATOR, address=1DBX...} + AddressEntry{offerId='null', context=AVAILABLE, address=1HN2...} + +Now search the file for the first match for the string `addr:1DBX...`. You should find a section that looks like the following: + + Key to watch: xpub... + addr:1ABC... hash160:f778... + DeterministicKey{pub HEX=02ff..., priv HEX=dfc8..., ...} + addr:1DBX... hash160:760d... + DeterministicKey{pub HEX=039d..., priv HEX=929d..., ...} + +*Note both the `pub HEX` and `priv HEX` values for the `addr:1DBX...` entry*, which should be the second entry in the list. + +You can now *reset your wallet password*. + +=== Step 3. Get trader's private key + +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`. + +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. + +When you have the trader's private key, move on to the next step. + +[[issue-payout]] +=== Step 4. Issue the manual dispute payout + +Now that you have all the necessary information, you can *open the Emergency multi-sig payout tool* by clicking `alt-g` in the dispute view: + +image:images/multisig-payout-tool.png[Emergency multi-sig payout tool] + +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. + +buyerPayoutAmount:: The amount in BTC that the buyer should be paid out, as noted above, e.g. `0.03` + +sellerPayoutAmount:: The amount in BTC the seller should be paid out, e.g. `0.0662` + +arbitratorPayoutAmount:: This value should always be `0`, as we no longer issue payouts to arbitrators + +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 + +buyerAddressString:: The buyer's bitcoin address + +sellerAddressString:: The seller's bitcoin address + +arbitratorAddressString:: The arbitrator's bitcoin address + +buyerPrivateKeyAsHex:: The buyer's private key (leave empty if buyer was not the winner) + +sellerPrivateKeyAsHex:: The seller's private key (leave empty if seller was not the winner) + +arbitratorPrivateKeyAsHex:: The arbitrator's private key + +buyerPubKeyAsHex:: The buyer's public key + +sellerPubKeyAsHex:: The seller's public key + +arbitratorPubKeyAsHex:: The arbitrator's public key + +P2SHMultiSigOutputScript:: The P2SH multi-sig output script hex value as copied from the block explorer + +When all values have been entered (and double-checked!), click `Sign and publish transaction` to issue the payout. + +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*. + + +== Trader instructions + +[WARNING] +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. + +=== Step 1. Get your public key from your arbitrator + +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. + +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. + +=== Step 2. Remove your wallet password [[remove-password]] + +Removing your wallet password is necessary in order to get the unencrypted value of your corresponding private key in the next step. + +Go to `Account > Wallet Password`, enter your password and click the `Remove password` button: + +image:images/password-active.png[wallet password active] + +When your wallet password has been removed, you should see the following: + +image:images/password-removed.png[wallet password removed] + +You can now move on to the next step. + +=== Step 3: Send your private key to your arbitrator + +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: + +image:images/wallet-data.png[wallet data dialog] + +At the bottom of the dialog, *check the box that reads `Include private keys`*: + +image:images/include-private-keys.png[include private keys] + +Then *click `Copy to clipboard`*. + +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. + +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. + +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*. + +Close the text editor. When prompted, *do not save the file*. + +Back in your Bisq client, *send your private key to your arbitrator* by pasting it into the support ticket chat window. + +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. + +=== Step 4: Reset your wallet password + +The final step is to reset your wallet password. + +Go to `Account > Wallet Password`, enter and confirm your password and click `Set password`.