Difference between revisions of "Manual payout"

From Bisq Wiki
Jump to navigation Jump to search
(Re-formatted to show the Bisq Manual Payout tool instructions before the coinbin instructions.)
(42 intermediate revisions by 5 users not shown)
Line 1: Line 1:
== Warning ==
+
== Overview ==
 +
 
 +
Funds for a Bisq trade are locked in a 2-of-2 multisig that is controlled only by the two parties involved.
 +
Bisq normally does all the work to sign and publish the payout at trade completion.
 +
However sometimes a trade can fail due to unforseen circumstances, leaving the funds stranded in the 2-of-2 multisig.
 +
When this happens, a Manual Payout may be necessary.
 +
 
 +
 
 +
== Using Bisq's Manual Payout tool ==
 +
The emergency payout tool is in Bisq, if you do a CTRL-G it will open. 
 +
 
 +
The purpose of the tool is to allow owners of a 2of2 multisig to issue a transaction which pays out the funds to their addresses.  The tool is designed to be used in collaboration with mediators but
 +
it could conceivably be used by the multisig key holders alone.
 +
 
 +
It is similar in operation to the tool "coinbin".
 +
 
 +
The tool operates in 4 steps:
 +
 
 +
# Fill input information;
 +
# Import/export details to trade participants;
 +
# Sign using each holder's private key;
 +
# Build and broadcast the payout.
 +
 
 +
 
 +
 
 +
=== Fill in inputs ===
 +
 
 +
Input information can be either filled in manually using information from the Bisq trade's Json contract, or for ease of use the same information can be imported from the Mediation ticket.
 +
 
 +
* If filling in manually, all fields on the "Inputs" tab must be entered.
 +
* If importing from Mediation, choose the Import menu option then pick your mediation ticket from the drop down list and press "Import from mediation ticket".
 +
 
 +
One important thing which the tool prompts you for is the "amountInMultisig" field.  This value is not known in Bisq, so the user (or Mediator) has to look it up on a Blockchain explorer and enter it completely accurately into the tool.  If it is incorrect in any way the resultant transaction will fail.  (Reason for this is that Segwit includes the amount as part of the signature inputs).
 +
 
 +
 
 +
=== Import/Export to trade participants ===
 +
 
 +
Once accurate input information has been entered, the same information needs to be passed to both owners of the multisig keys (the two traders).  This is what the "Export" menu item is for.  It translates the input field data into a code which can be DM'd or emailed to the participants, which they can enter via the "Import" menu (& "Import from String" option). 
 +
 
 +
The important thing is that each participant have EXACTLY the same information entered into the Inputs section of the tool.  If there is any discrepancy between the inputs that each participant signs, then the transaction will be invalid.
 +
 
 +
Note that if the two traders have access to the mediation ticket they can Import from the ticket themselves.  But it is generally best for Mediator to Export their filled in fields to both traders (via DM).
 +
 
 +
 
 +
=== Sign ===
 +
 
 +
Both participants have to sign the inputs.  This is done from the Sign menu, for convenience there is a "Locate key in wallet" button which will scan the user's wallet for a key which matches the inputs.  "Generate signature" will sign the inputs using the key at the top of the screen.  Users could alternatively choose to locate the key themselves, and paste it into the "privateKeyHex" field before doing "Generate signature".
 +
 
 +
Once the signature has been generated each participant should send it to the person who will build and broadcast the transaction (usually the Mediator).
 +
 
 +
 
 +
=== Build & Broadcast ===
 +
 
 +
Once both signatures have been provided, they can be pasted into the Build screen at which time the "Build" button at the bottom of that screen should be pressed.  It will generate the TxID and transaction hex into the text area.  The transaction hex can be verified using your own tools* or simply broadcast to the network using the "Broadcast" button (or alternatively send it yourself using your Bitcoin node). 
 +
 
 +
 
 +
* NB: "https://bitaps.com/broadcast" has a "Preview" feature that tests if the transaction is acceptable to the mempool before actually sending it.  Any errors in the transaction will be listed, or if it is good it will say "Test mempool transaction accepted" and give the option to broadcast it at that point.
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
== Alternate method using coinbin ==
  
 
In this process you copy and paste your private keys from the Bisq software into a web browser. As a precaution it is advised you remove all of your funds from this wallet before starting this procedure.
 
In this process you copy and paste your private keys from the Bisq software into a web browser. As a precaution it is advised you remove all of your funds from this wallet before starting this procedure.
  
== Precautions ==
+
=== Precautions ===
  
 
This method is only necessary in extreme occasions where one of the traders may not be available. Therefore it is  important to make sure that the person who constructs the transaction does not defraud the other signers.
 
This method is only necessary in extreme occasions where one of the traders may not be available. Therefore it is  important to make sure that the person who constructs the transaction does not defraud the other signers.
  
== What you need ==
+
=== What you need ===
  
 
This document uses open source tools (other than Bisq) to create, sign and broadcast transactions of funds locked in multisig transactions.
 
This document uses open source tools (other than Bisq) to create, sign and broadcast transactions of funds locked in multisig transactions.
Line 20: Line 89:
 
* Bisq software
 
* Bisq software
 
* [http://explorerzydxu5ecjrkwceayqybizmpjjznk5izmitf2modhcusuqlid.onion Blockstream's block explorer]
 
* [http://explorerzydxu5ecjrkwceayqybizmpjjznk5izmitf2modhcusuqlid.onion Blockstream's block explorer]
* [http://4zpinp6gdkjfplhk.onion Coinbin web wallet]
+
* [https://coinb.in/ Coinbin web wallet]
 
* [https://www.torproject.org/ Tor browser]
 
* [https://www.torproject.org/ Tor browser]
  
== 1. Get private keys ==
 
<ol type="a">
 
<li>To access your Bisq wallet's private key press <code>Ctrl + j</code>, <code>alt +j</code> or <code>cmd + j</code>.</li>
 
<li>Check <code>Include private keys</code> and click <code>COPY TO CLIPBOARD</code>.</li>
 
<li>Copy, paste and save that information in a <code>bisqWallet.txt</code> file.</li>
 
</ol>
 
  
== 2. Get multisg public keys ==
+
 
 +
 
 +
=== Get multisig public keys ===
  
 
Each trader involved can get their public keys and the other trader's public keys in their trade JSON contract.  
 
Each trader involved can get their public keys and the other trader's public keys in their trade JSON contract.  
<ol type="a">
+
# Find your trade under <code>PORTFOLIO</code>.
<li>Find your trade under <code>PORTFOLIO</code>.</li>
+
# Click the <code>i</code> icon next to the trade ID, and at the bottom click <code>VIEW CONTRACT IN JSON FORMAT</code>. At the end, you see the Buyer and Seller public keys:
<li>Click the <code>i</code> icon next to the trade ID, and at the bottom click <code>VIEW CONTRACT IN JSON FORMAT</code>. At the end, you see the Buyer and Seller public keys:</li>
 
</ol>
 
 
  <nowiki>
 
  <nowiki>
BuyerMultiSigPubKeyHex:
+
BuyerMultiSigPubKeyHex: <hex value>
SellerMultiSigPubKeyHex:
+
SellerMultiSigPubKeyHex: <hex value></nowiki>
</nowiki>
 
  
 +
=== Get private keys ===
  
'''Legacy protocol'''
+
To access your Bisq wallet private key
 +
# Press <code>Ctrl + j</code>, <code>alt +j</code> or <code>cmd + j</code>.
 +
# Check <code>Include private keys</code> and click <code>COPY TO CLIPBOARD</code>.
 +
# In the text editor, search for the public key value. You are looking for an entry that reads <code>DeterministicKey{pub HEX=<hex value></code> where <hex value> is the public key.
 +
# When you've found this entry, select and copy the <code>priv WIF=<hex value></code> value that immediately follows the pub HEX value. This value is the private key.
 +
# Copy, paste and save that information in a <code>bisqWallet.txt</code> file.
  
If resolving a trade with the old protocol that involved a 2 out of 3 multisig, a third public key belonging to the arbitrator is necessary. The arbitrator can get this public key by following the steps above and search in their own <code>bisqWallet.txt</code> file for it. They can find it by looking for the public key for their Arbitrator address. It is the one in the line with <code>context=ARBITRATOR</code>.
+
''Note: If your wallet uses a password, you will need to remove the password to view the private keys in wallet data.''
  
An alternative way to get the arbitrator's public key is to look for it in the blockchain. This can be done if at least one of the traders paid the trading fees in BTC.
+
=== Get payout addresses ===
 
 
By tracking the BTC trading fee you can find the cluster of other trades that arbitrator was involved in. Then you need to find to Payout transactions - spending from a 2 out of 3 multisig. In these transactions will be able to find 3 revealed public keys for each trade. The one that is present in both trades is the arbitrator's.
 
 
 
== 3. Get payout addresses ==
 
  
 
At the end of the JSON contract file you can also find the intended payout address for each trader:
 
At the end of the JSON contract file you can also find the intended payout address for each trader:
 
  <nowiki>
 
  <nowiki>
makerPayoutAddressString:
+
makerPayoutAddressString: <address value>
takerPayoutAddressString:</nowiki>
+
takerPayoutAddressString: <address value></nowiki>
  
== 4. Recreating Redeem script ==
+
=== Recreating Redeem script ===
  
 
For all the web interactions use the Tor browser.  
 
For all the web interactions use the Tor browser.  
<ol type="a">
+
# Go to the [https://coinb.in/ Coinbin web wallet]:
<li>Go to the [http://4zpinp6gdkjfplhk.onion Coinbin web wallet]:</li>
+
# At the top click <code>New</code> and from the dropdown menu choose <code>MultiSig Address</code>
<li>At the top click <code>New</code> and from the dropdown menu choose <code>MultiSig Address</code></li>
+
# Paste the three public keys in the following order 1) SellerMultiSigPubKeyHex, 2) BuyerMultiSigPubKeyHex
<li>Paste the three public keys in the following order:</li>
+
# Click <code>submit</code> to see an address and a Redeem Script. Make sure the address matches the multisig address for the trade. If not, try to change the order of the public keys.
*Arbitrator
+
# Copy and save the Redeem Script.
*BuyerMultiSigPubKeyHex
+
 
*SellerMultiSigPubKeyHex
+
=== Creating transaction ===
<li>Click <code>submit</code> to see an address and a Redeem Script. Make sure the address matches the multisig address for the trade. If not, try to change the order of the public keys.</li>
 
<li>Copy and save the Redeem Script.</li>
 
</ol>
 
  
== 5. Creating transaction ==
+
# Again, click <code>New</code> at the top, but this time choose <code>Transaction</code> from the dropdown menu.
<ol type="a">
+
# Paste the Redeem Script in the text field at the top and click <code>Load</code>. It should take a few seconds and then return the value locked in the multisig.
<li>Again, click <code>New</code> at the top, but this time choose <code>Transaction</code> from the dropdown menu.</li>
+
# For the first input fill in an address from <code>makerPayoutAddressString</code> and the respective trade amount.
<li>Paste the Redeem Script in the text field at the top and click <code>Load</code>. It should take a few seconds and then return the value locked in the multisig.</li>
+
# Add a new output by clicking the <code>+</code> sign next to the <code>amount</code> field. For this second output paste the address that belongs to <code>takerPayoutAddressString</code> and the respective trade amount.
<li>For the first input fill in an address from <code>makerPayoutAddressString</code> and the respective trade amount.</li>
+
# Copy and save the transaction.
<li>Add a new output by clicking the <code>+</code> sign next to the <code>amount</code> field. For this second output paste the address that belongs to <code>takerPayoutAddressString</code> and the respective trade amount.</li>
+
# Click <code>submit</code> to obtain an encoded transaction string.
<li>Click <code>submit</code> to obtain an encoded transaction string.</li>
 
<li>Copy and save the transaction.</li>
 
</ol>
 
  
== 6. Verify transaction ==
+
=== Verify transaction ===
  
 
Click <code>Verify</code> at the top and paste the encoded string obtained from the step 5.e. Verify it all is correct before moving to the next step.
 
Click <code>Verify</code> at the top and paste the encoded string obtained from the step 5.e. Verify it all is correct before moving to the next step.
  
== 7. Sign transaction ==
+
=== Sign transaction ===
<ol type="a">
 
<li>Click <code>Sign</code> at the top of the page and paste your WIF private key obtained in step 1 in the <code>Private key</code> text field and the encoded transaction in the text field below.<br>To find the private key, search your <code>bisqWallet.txt</code> file for the value of the <code>BuyerMultiSigPubKeyHex</code> (or <code>SellerMultiSigPubKeyHex</code> if you are the seller), obtained in step 2. The private key beginning with <code>priv WIF=</code> is written after the search result. Ensure that the pasted private key is only the part after the <code>priv WIF=</code>.</li>
 
<li>Click <code>Submit</code> to get a new encoded transaction string. </li>
 
<li>Copy and save it and share it with the other parties of the multisig so they can sign and broadcast it.</li>
 
</ol>
 
  
== 8. Second signature and broadcast ==
+
# Click <code>Sign</code> at the top of the page and paste your WIF private key in the <code>Private key</code> text field and the encoded transaction in the text field below.
 +
# Click <code>Submit</code> to get a new encoded transaction string.  
 +
# Copy and save it and share it with the other parties of the multisig so they can sign and broadcast it.
  
The second signer clicks <code>Verify</code> at the top of the Coinbin website and pastes the encoded string the previous signer shared with you. If you are ok with it, click <code>Sign</code> at the top of the page and paste your WIF private key from step 1 on the <code>Private key</code> text field and the encoded transaction shared with you in the text field below. Then, click <code>Submit</code> to get a new encoded transaction string. Copy and save it.
+
=== Second signature and broadcast ===
  
You can verify the transaction before broadcasting.
+
# The second signer clicks <code>Verify</code> at the top of the Coinbin website and pastes the encoded string the previous signer shared with you. If you are ok with it, click <code>Sign</code> at the top of the page and paste your WIF private key text field and the encoded transaction shared with you in the text field below.
 +
# Click <code>Submit</code> to get a new encoded transaction string.
 +
# Copy and save it.
  
If everything is correct, click <code>Broadcast</code> at the top of the page, paste the encoded transaction string obtained after you signed the transaction and click <code>Submit</code>.
+
=== Verify transaction before broadcasting===
  
After all is done, delete the <code>bisqWallet.txt</code> file created in step 1.
+
# Confirm everything is correct and click <code>Broadcast</code> at the top of the page.
 +
# After you have signed the transaction paste the encoded transaction string and click <code>Submit</code>.
 +
# When complete, delete the <code>bisqWallet.txt</code> file created in step 1.

Revision as of 17:00, 15 May 2022

Overview

Funds for a Bisq trade are locked in a 2-of-2 multisig that is controlled only by the two parties involved. Bisq normally does all the work to sign and publish the payout at trade completion. However sometimes a trade can fail due to unforseen circumstances, leaving the funds stranded in the 2-of-2 multisig. When this happens, a Manual Payout may be necessary.


Using Bisq's Manual Payout tool

The emergency payout tool is in Bisq, if you do a CTRL-G it will open.

The purpose of the tool is to allow owners of a 2of2 multisig to issue a transaction which pays out the funds to their addresses. The tool is designed to be used in collaboration with mediators but it could conceivably be used by the multisig key holders alone.

It is similar in operation to the tool "coinbin".

The tool operates in 4 steps:

  1. Fill input information;
  2. Import/export details to trade participants;
  3. Sign using each holder's private key;
  4. Build and broadcast the payout.


Fill in inputs

Input information can be either filled in manually using information from the Bisq trade's Json contract, or for ease of use the same information can be imported from the Mediation ticket.

  • If filling in manually, all fields on the "Inputs" tab must be entered.
  • If importing from Mediation, choose the Import menu option then pick your mediation ticket from the drop down list and press "Import from mediation ticket".

One important thing which the tool prompts you for is the "amountInMultisig" field. This value is not known in Bisq, so the user (or Mediator) has to look it up on a Blockchain explorer and enter it completely accurately into the tool. If it is incorrect in any way the resultant transaction will fail. (Reason for this is that Segwit includes the amount as part of the signature inputs).


Import/Export to trade participants

Once accurate input information has been entered, the same information needs to be passed to both owners of the multisig keys (the two traders). This is what the "Export" menu item is for. It translates the input field data into a code which can be DM'd or emailed to the participants, which they can enter via the "Import" menu (& "Import from String" option).

The important thing is that each participant have EXACTLY the same information entered into the Inputs section of the tool. If there is any discrepancy between the inputs that each participant signs, then the transaction will be invalid.

Note that if the two traders have access to the mediation ticket they can Import from the ticket themselves. But it is generally best for Mediator to Export their filled in fields to both traders (via DM).


Sign

Both participants have to sign the inputs. This is done from the Sign menu, for convenience there is a "Locate key in wallet" button which will scan the user's wallet for a key which matches the inputs. "Generate signature" will sign the inputs using the key at the top of the screen. Users could alternatively choose to locate the key themselves, and paste it into the "privateKeyHex" field before doing "Generate signature".

Once the signature has been generated each participant should send it to the person who will build and broadcast the transaction (usually the Mediator).


Build & Broadcast

Once both signatures have been provided, they can be pasted into the Build screen at which time the "Build" button at the bottom of that screen should be pressed. It will generate the TxID and transaction hex into the text area. The transaction hex can be verified using your own tools* or simply broadcast to the network using the "Broadcast" button (or alternatively send it yourself using your Bitcoin node).


  • NB: "https://bitaps.com/broadcast" has a "Preview" feature that tests if the transaction is acceptable to the mempool before actually sending it. Any errors in the transaction will be listed, or if it is good it will say "Test mempool transaction accepted" and give the option to broadcast it at that point.







Alternate method using coinbin

In this process you copy and paste your private keys from the Bisq software into a web browser. As a precaution it is advised you remove all of your funds from this wallet before starting this procedure.

Precautions

This method is only necessary in extreme occasions where one of the traders may not be available. Therefore it is important to make sure that the person who constructs the transaction does not defraud the other signers.

What you need

This document uses open source tools (other than Bisq) to create, sign and broadcast transactions of funds locked in multisig transactions. To spend out of a multisig, two things are needed:

  • A redeem script.
  • Enough private keys to meet the minimum multisig threshold. Use the string in priv WIF= instead of priv HEX=.


Bisq does not provide the Redeem Script for the multisig, but we can recreate it with all the public keys involved in the multisig.

Tools you need:



Get multisig public keys

Each trader involved can get their public keys and the other trader's public keys in their trade JSON contract.

  1. Find your trade under PORTFOLIO.
  2. Click the i icon next to the trade ID, and at the bottom click VIEW CONTRACT IN JSON FORMAT. At the end, you see the Buyer and Seller public keys:
BuyerMultiSigPubKeyHex: <hex value>
SellerMultiSigPubKeyHex: <hex value>

Get private keys

To access your Bisq wallet private key

  1. Press Ctrl + j, alt +j or cmd + j.
  2. Check Include private keys and click COPY TO CLIPBOARD.
  3. In the text editor, search for the public key value. You are looking for an entry that reads DeterministicKey{pub HEX=<hex value> where <hex value> is the public key.
  4. When you've found this entry, select and copy the priv WIF=<hex value> value that immediately follows the pub HEX value. This value is the private key.
  5. Copy, paste and save that information in a bisqWallet.txt file.

Note: If your wallet uses a password, you will need to remove the password to view the private keys in wallet data.

Get payout addresses

At the end of the JSON contract file you can also find the intended payout address for each trader:

makerPayoutAddressString: <address value>
takerPayoutAddressString: <address value>

Recreating Redeem script

For all the web interactions use the Tor browser.

  1. Go to the Coinbin web wallet:
  2. At the top click New and from the dropdown menu choose MultiSig Address
  3. Paste the three public keys in the following order 1) SellerMultiSigPubKeyHex, 2) BuyerMultiSigPubKeyHex
  4. Click submit to see an address and a Redeem Script. Make sure the address matches the multisig address for the trade. If not, try to change the order of the public keys.
  5. Copy and save the Redeem Script.

Creating transaction

  1. Again, click New at the top, but this time choose Transaction from the dropdown menu.
  2. Paste the Redeem Script in the text field at the top and click Load. It should take a few seconds and then return the value locked in the multisig.
  3. For the first input fill in an address from makerPayoutAddressString and the respective trade amount.
  4. Add a new output by clicking the + sign next to the amount field. For this second output paste the address that belongs to takerPayoutAddressString and the respective trade amount.
  5. Copy and save the transaction.
  6. Click submit to obtain an encoded transaction string.

Verify transaction

Click Verify at the top and paste the encoded string obtained from the step 5.e. Verify it all is correct before moving to the next step.

Sign transaction

  1. Click Sign at the top of the page and paste your WIF private key in the Private key text field and the encoded transaction in the text field below.
  2. Click Submit to get a new encoded transaction string.
  3. Copy and save it and share it with the other parties of the multisig so they can sign and broadcast it.

Second signature and broadcast

  1. The second signer clicks Verify at the top of the Coinbin website and pastes the encoded string the previous signer shared with you. If you are ok with it, click Sign at the top of the page and paste your WIF private key text field and the encoded transaction shared with you in the text field below.
  2. Click Submit to get a new encoded transaction string.
  3. Copy and save it.

Verify transaction before broadcasting

  1. Confirm everything is correct and click Broadcast at the top of the page.
  2. After you have signed the transaction paste the encoded transaction string and click Submit.
  3. When complete, delete the bisqWallet.txt file created in step 1.