diff --git a/backup-recovery.adoc b/backup-recovery.adoc new file mode 100644 index 0000000..c1dadba --- /dev/null +++ b/backup-recovery.adoc @@ -0,0 +1,126 @@ += Backup and Recovery +:imagesdir: ./images +:!figure-caption: + +All Bisq data is stored right on your computer. It's never sent or stored to 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. + +As you use Bisq, you'll accumulate data you will want to save, like your payment account details, 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. + +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. + +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. + +== Data Directory + +=== Back Up + +All Bisq data is stored in one place: + +* macOS: `/Users//Library/Application Support/Bisq` +* Linux: `/home//.local/share/Bisq` +* Windows 7+: `C:\Documents and Settings\\AppData\Roaming\Bisq` +* Windows XP: `C:\Documents and Settings\\Application Data\Bisq` + +**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. + +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. + +=== Restore + +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. + +Then delete the whole `Bisq` folder and replace it with the `Bisq` folder from your backup. + +=== Details + +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. + +The other notable item is `btc_mainnet`, which is the main folder containing data for your payment accounts, Tor setup, and wallet. + +== Payment Accounts + +There are 2 components to payment accounts on Bisq: account details and account aging. + +**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. + +**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. + +To restore payment account details, simply import the file you exported earlier through the same interface. + +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. + +If you don't have an accounts export file, but you have a full backup of the data directory, you can still fully restore your accounts details and accounts aging by manually copying the following files to your data directory from a backup: + +* `btc_mainnet/db/UserPayload` (account details and salt) +* `btc_mainnet/keys/sig.key` (key for signing p2p messages) + +**Again, please make sure you don't have any open offers, trades, or disputes before changing `sig.key`.** + +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. + +== Tor State + +Bisq runs as a Tor hidden service to protect your privacy. + +[.float-group] +-- + +[.right.text-center] +.Local reputation. +image::repeat-trading-peer.png[Local reputation,300,300] + +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. + +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. + +-- + +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. + +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_. + +**Make sure you don't have any open offers, trades, or disputes before changing your onion address, as doing so will make you unreachable.** + +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. + +== Wallet Data + +Your wallet data is stored in `btc_mainnet/wallet`. There are 3 primary ways to work with wallet backup files to resolve wallet issues. + +=== Resync SPV chain + +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 `btcmainnet/wallet` (just be advised that you will need to manually restart Bisq twice to complete the resync). + +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. + +NOTE: Resyncs can take a while, depending on how old your wallet it 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! + +=== Restore wallet backup + +If issues persist, you can try to restore a backup wallet 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 backup wallet 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. + +Start Bisq and see if your issue is fixed. If not, repeat with another backup file. + +=== Switch to a new data direcory + +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. + +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. + +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). + +Once you're retrieved your funds, here's how to generate a new data directory: + +* close Bisq +* delete the whole `Bisq` directory (after backing it up, just in case) +* start Bisq (this will generate a fresh new data directory) +* send your funds back into Bisq +* optional: restore payment accounts and/or Tor keys through the processes outlined above + +**Make sure you don't have any open offers, trades, or disputes before doing this.** + +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. + +== Trade History + +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. diff --git a/images/repeat-trading-peer.png b/images/repeat-trading-peer.png new file mode 100644 index 0000000..bc0cdab Binary files /dev/null and b/images/repeat-trading-peer.png differ diff --git a/index.adoc b/index.adoc index e996c35..02daa4e 100644 --- a/index.adoc +++ b/index.adoc @@ -24,7 +24,7 @@ Docs without hyperlinks haven't been written yet. If you want to write one, <> — _Download, set up and start trading with Bisq in minutes_ * <> — _Trade, vote, and govern Bisq through the DAO with BSQ_ * <> — _Set a password and save your seed words to keep your bitcoin safe_ - * Backup and Recovery — _Maintain backups to keep your settings and history safe_ + * <> — _Maintain backups to keep your settings and history safe_ * Staying Private — _Maximize control over your personal info and trading data_ * <> — _Know what's expected of you and others when trading_ * Fees and Security Deposits — _Understand how your bitcoin is used and kept safe when trading_