Git-Mirrors/haveno
1
0
Fork 0
mirror of https://github.com/haveno-dex/haveno.git synced 2025-10-11 18:10:50 -04:00
Code Issues Projects Releases Packages Wiki Activity

Bisq

Browse source
This commit is contained in:
woodser 2021-05-04 20:20:01 -04:00
commit 8a38081c04
2800 changed files with 344130 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

11
docs/README.md Normal file
View file

@ -0,0 +1,11 @@
# Bisq developer docs
- [CONTRIBUTING.md](../CONTRIBUTING.md): Understand Bisq's contribution and compensation guidelines
- [build.md](build.md): Build and run Bisq at the command line
- [idea-import.md](idea-import.md): Import Bisq sources into IntelliJ IDEA
- [Makefile](../Makefile): (new) Set up a self-contained local Bisq network on Bitcoin regtest
- [dev-setup.md](dev-setup.md): (deprecated) Set up a self-contained local Bisq network on Bitcoin regtest
- [dao-setup.md](dao-setup.md): (deprecated) Set up a complete Bisq DAO development environment
- [testing.md](testing.md): Learn about the Bisq testing process and how you can contribute.
Looking for user-facing documentation? See https://docs.bisq.network.

179
docs/autosetup-regtest-dao/README.md Normal file
View file

@ -0,0 +1,179 @@
# Automated setup of regtest DAO - for Linux
The goal of these helper scripts is to set up a bisq DAO from scratch. The scripts run `bitcoind` in regtest mode for you and a `seed node`, `alice` and `bob` instances.
We assume the user is in the `autosetup-regtest-dao` directory. It is ok to move the directory, but please move it as a whole. Also `bitcoin-qt`, `bitcoin-cli`, `bitcoin-tx`, `jq` and `bc` has to be installed on the system. Do not change the shipped `bitcoin.conf` file as it will break things.
## Steps to spin up a fresh DAO (we assume the user is in the autosetup-regtest-dao directory):
1. Set up `bitcoin-qt` to run in the `autosetup-regtest-dao` directory, it detects when the `bitcoin-qt` instance comes up and once it is ready the script queries the number of blocks. If there are less then 101 blocks (fresh start) the script generates 101 blocks for you so you have an available input that will be later used for the genesis tx creation.
```
./start_bitcoind.sh
```
Example output (note the below errors are normal and can be ignored):
```
user@host:~/bin/KanoczTomas/bisq/docs/autosetup-regtest-dao$ ./start_bitcoind.sh
error: Could not connect to the server 127.0.0.1:18443
Make sure the bitcoind server is running and that you are connecting to the correct RPC port.
error code: -28
error message:
Loading wallet...
./generate_101_blocks.sh: found less blocks then 101, generating ...
./blocknotify: line 2: echo: write error: Broken pipe
./blocknotify: line 2: echo: write error: Broken pipe
./blocknotify: line 2: echo: write error: Broken pipe
./blocknotify: line 2: echo: write error: Broken pipe
./blocknotify: line 2: echo: write error: Broken pipe
./blocknotify: line 2: echo: write error: Broken pipe
./blocknotify: line 2: echo: write error: Broken pipe
./blocknotify: line 2: echo: write error: Broken pipe
./blocknotify: line 2: echo: write error: Broken pipe
./blocknotify: line 2: echo: write error: Broken pipe
[
"24e04970e3b55fe45efde314cc959a7baeef379d74d322bc132b723235f1e8ca",
<truncated output for compactness>
"2d4aaa455c681b604a683437c657e23b19af0b614f5f822c4c7aecee865b5f5f"
]
./generate_101_blocks.sh: done, exiting
```
2. Open a new terminal (preferably a new tab), go to the `bisq` folder and start the `create_genesis.sh` script. The script tests for a running bitcoind node in regtest, so make sure step 1 was successful.
```
cd bisq
./create_genesis.sh
```
example output:
```
user@host:~/bin/KanoczTomas/bisq/docs/autosetup-regtest-dao/bisq$ ./create_genesis.sh
testing if bitcoind is running: bitcoind is running, all is ok!
Please provide Alice's BSQ Address
```
3. We need the BSQ address of `Alice`. Go to the `bisq` directory and start the `Alice` instance. Wait until the instance starts up then go to `DAO -> Receive` and copy the BSQ address. Note the address starts with a `B`. Open a new terminal and enter the commands below to start `Alice`. Then wait for the gui to start and paste the BSQ address to `create_genesis.sh` which is still running from step 2.
```
cd bisq
./alice
```
4. Enter the amount of BTC in the `create_genesis.sh` script you want `Alice` to receive as BSQ.
Example output:
```
user@host:~/bin/KanoczTomas/bisq/docs/autosetup-regtest-dao/bisq$ ./create_genesis.sh
testing if bitcoind is running: bitcoind is running, all is ok!
Please provide Alice's BSQ Address
Bn2iUHwJQTreQaoajKwnT6h7pYF9nCWULJA
How much BTC to turn to BSQ for Alice? (sum must be 2.5BTC)
1
Alice will receive 1000000.00 BSQ to Bn2iUHwJQTreQaoajKwnT6h7pYF9nCWULJA
```
5. We need the BSQ address of `Bob`. Go to the `bisq` directory and start the `Bob` instance. Wait until the instance starts up then go to `DAO -> Receive` and copy the BSQ address. Note the address starts with a `B`. Open a new terminal and enter the commands below to start `Bob`. Then wait for the gui to start and paste the BSQ address to `create_genesis.sh` which is still running from step 2.
```
cd bisq
./bob
```
6. Enter the amount of BTC in the `create_genesis.sh` script you want `Bob` to receive as BSQ.
Example output:
```
tk@workbook:~/bin/KanoczTomas/bisq/docs/autosetup-regtest-dao/bisq$ ./create_genesis.sh
testing if bitcoind is running: bitcoind is running, all is ok!
Please provide Alice's BSQ Address
Bn2iUHwJQTreQaoajKwnT6h7pYF9nCWULJA
How much BTC to turn to BSQ for Alice? (sum must be 2.5BTC)
1
Alice will receive 1000000.00 BSQ to Bn2iUHwJQTreQaoajKwnT6h7pYF9nCWULJA
Please provide Bob's BSQ Address
BmoccyQEENPwxeZUdPAnDejEeTzykD9Kdbo
How much BTC to turn to BSQ for Bob? (sum must be 2.5BTC)
1.5
Bob will receive 1500000.00 BSQ to BmoccyQEENPwxeZUdPAnDejEeTzykD9Kdbo
got address 2MwNUS6czZZ8tFeFArujf1AghFZUfcJmgRx
sending 2.5001 BTC to 2MwNUS6czZZ8tFeFArujf1AghFZUfcJmgRx
txid is: d8c9d0caaaa69ad26e3dbe2176cd7fd48a4509b96cd902982fbc9811211cf20e
creating genesis tx for you
The raw genesis tx is: 020000000001010ef21c211198bc2f9802d96cb909458ad47fcd7621be3d6ed29aa6aacad0c9d80000000017160014d3316afa653bb7ca1f7bfd2395c373c979fd14ddffffffff0200e1f505000000001976a914e8884212730dd91d620b92d2e95245baf776d78b88ac80d1f008000000001976a91458d35f88e65ded63cb22a25ffda6f83a0209822b88ac0247304402204395a123c499f05bdc9b458459d97df1910feb9a43d66b7ca7e28a91c6cf19a702203ddb3fb891442bb76a2a8e267b4fec99c8a40064461556a03a799e787d08334f01210397ff7d1aa76f2fb241b0354332bb1e9be0520e744a8a2a7e5e088a92a7c09dd200000000
Please verify if decoded tx looks ok:
{
"txid": "a876c877de410480530f7e8fa7e34034085db4db603d30a5635610fb59e646b2",
"hash": "81923b096990db55e44730a4c3af975b1ecd995d8cbfdac939b16081249aa8bc",
"version": 2,
"size": 251,
"vsize": 170,
"weight": 677,
"locktime": 0,
"vin": [
{
"txid": "d8c9d0caaaa69ad26e3dbe2176cd7fd48a4509b96cd902982fbc9811211cf20e",
"vout": 0,
"scriptSig": {
"asm": "0014d3316afa653bb7ca1f7bfd2395c373c979fd14dd",
"hex": "160014d3316afa653bb7ca1f7bfd2395c373c979fd14dd"
},
"txinwitness": [
"304402204395a123c499f05bdc9b458459d97df1910feb9a43d66b7ca7e28a91c6cf19a702203ddb3fb891442bb76a2a8e267b4fec99c8a40064461556a03a799e787d08334f01",
"0397ff7d1aa76f2fb241b0354332bb1e9be0520e744a8a2a7e5e088a92a7c09dd2"
],
"sequence": 4294967295
}
],
"vout": [
{
"value": 1,
"n": 0,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 e8884212730dd91d620b92d2e95245baf776d78b OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a914e8884212730dd91d620b92d2e95245baf776d78b88ac",
"reqSigs": 1,
"type": "pubkeyhash",
"addresses": [
"n2iUHwJQTreQaoajKwnT6h7pYF9nCWULJA"
]
}
},
{
"value": 1.5,
"n": 1,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 58d35f88e65ded63cb22a25ffda6f83a0209822b OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a91458d35f88e65ded63cb22a25ffda6f83a0209822b88ac",
"reqSigs": 1,
"type": "pubkeyhash",
"addresses": [
"moccyQEENPwxeZUdPAnDejEeTzykD9Kdbo"
]
}
}
]
}
Press enter to broadcast transaction, ctrl+c otherwise
```
7. verify if the tx shown as json is ok (the sum of outputs must be 2.5 to be valid). Note the script does not check the sum of the outputs as one needs to create an invalid genesis tx as well to test things. Press `enter` if tx looks ok.
8. Once confirmed the script will broadcast the genesis tx to the regtest blockchain and setup the `config.sh` file in the `bisq` directory which is used by the `seed_node`, `alice` and `bob` scripts. It populates the genesis txid and genesis block height so the instances can be launched accordingly.
Example output:
```
... <output ommited - see step above>
Press enter to broadcast transaction, ctrl+c otherwise
Genesis txid is:
a876c877de410480530f7e8fa7e34034085db4db603d30a5635610fb59e646b2
Mining genesis tx for you
genesis_block is 39249aab4e42c85e14f59517ec6b45305fdc7d660315c6602aab1a1b7b96cd3b
genesis_height is 102
your conf file was modified accordingly
dao setup done
```
9. Start the `seed` node in full DAO node using the `seed_node` script. Make sure you are in the `bisq` directory.
```
cd bisq
./seed_node
```
10. Restart `Alice` and `Bob` you should see BSQ visible on the `DAO` page. Note the `seed node` is a full node and `alice`/`bob` are lite nodes in this setup.
## Continuing work on the existing setup
1. Just run `start_bitcoind.sh` script and spin up `seed node`, `alice` and `bob` with respected scripts.
## Clearing the DAO - for a fresh start
1. Run `clean.sh`. It will clear the bitcoind files and bisq files from `~/.local/share/` directory. Make sure your `bitcoind/bitcoin-qt` is stopped before running.
```
user@host:~/bin/KanoczTomas/bisq/docs/autosetup-regtest-dao$ ./clean.sh
DANGER! This will nuke your bitcoin regtest dir and bisq seed, alice and bob regtest dirs as well!
Press Enter to continue, otherwise ctrl+c
cleaned bitcoind home and bisq seed, alice, bob instances. The conf file for bisq was reset to dao=false
```

4
docs/autosetup-regtest-dao/bisq/alice Executable file
View file

@ -0,0 +1,4 @@
#!/bin/bash
. ./config.sh
~/bin/bisq/bisq-desktop --baseCurrencyNetwork=BTC_REGTEST --useLocalhostForP2P=true --useDevPrivilegeKeys=true --nodePort=5555 --appName=bisq-BTC_REGTEST_Alice --daoActivated=$dao --genesisBlockHeight=$genesis_height --genesisTxId=$genesis_tx

4
docs/autosetup-regtest-dao/bisq/bob Executable file
View file

@ -0,0 +1,4 @@
#!/bin/bash
. ./config.sh
~/bin/bisq/bisq-desktop --baseCurrencyNetwork=BTC_REGTEST --useLocalhostForP2P=true --useDevPrivilegeKeys=true --nodePort=6666 --appName=bisq-BTC_REGTEST_Bob --daoActivated=$dao --genesisBlockHeight=$genesis_height --genesisTxId=$genesis_tx

7
docs/autosetup-regtest-dao/bisq/config.sh Normal file
View file

@ -0,0 +1,7 @@
genesis_tx="e90c357baa66af5b62ed8b2ac8956b1391cde08bf74347cf24f58d323ad9cd76"
genesis_height=102
rpcuser="bisq"
rpcpassword="bisq"
blocknotifyport=5120
rpcport=18443
dao="false"

95
docs/autosetup-regtest-dao/bisq/create_genesis.sh Executable file
View file

@ -0,0 +1,95 @@
#!/bin/bash
. ./config.sh
bitcoin_cli="bitcoin-cli -regtest -datadir=.."
echo -en "testing if bitcoind is running: "
$bitcoin_cli getblockcount &>/dev/null
if [ $? -eq 1 ];then
echo "bitcoind not running, please run it first!"
exit 1
fi
echo -en "bitcoind is running, all is ok!\n"
echo "Please provide Alice's BSQ Address"
read address_alice
echo "How much BTC to turn to BSQ for Alice? (sum must be 2.5BTC)"
read value_alice
echo "Alice will receive $(echo "scale=2; $value_alice * 1000000.00"|bc -l) BSQ to $address_alice"
echo "Please provide Bob's BSQ Address"
read address_bob
echo "How much BTC to turn to BSQ for Bob? (sum must be 2.5BTC)"
read value_bob
echo "Bob will receive $(echo "scale=2; $value_bob * 1000000.00"|bc) BSQ to $address_bob"
function generate_prevtx_json(){
json_file="prevtxs.json"
local tx_data=$1
local txid=$2
local vout=$(echo $tx_data | jq '.n')
local scriptPubkey=$(echo $tx_data | jq '.scriptPubKey.hex')
local amount=$(echo $tx_data | jq '.value')
echo -en "[{\n" > $json_file
echo -en " \"txid\": \"${txid}\",\n" >> $json_file
echo -en " \"vout\": ${vout},\n" >> $json_file
echo -en " \"scriptPubKey\": ${scriptPubkey},\n" >> $json_file
echo -en " \"amount\": ${amount}\n" >> $json_file
echo -en "}]\n" >> $json_file
}
function generate_privkeys_json(){
json_file="privatekeys.json"
local address=$1
local privkey=$($bitcoin_cli dumpprivkey $address)
echo -en "[\"$privkey\"]\n" > $json_file
}
function edit_conf_file() {
local conf_file="config.sh"
local genesis_tx=$1
local genesis_height=$2
sed -r 's/genesis_tx=.*/genesis_tx="'"$genesis_tx"'"/' -i $conf_file
sed -r 's/genesis_height=.*/genesis_height='"$genesis_height"'/' -i $conf_file
sed -r 's/dao=.*/dao="true"/' -i $conf_file
}
genesis_input_address=$($bitcoin_cli getnewaddress "genesis tx")
echo "got address $genesis_input_address"
echo "sending 2.5001 BTC to $genesis_input_address"
genesis_input_txid=$($bitcoin_cli sendtoaddress $genesis_input_address 2.5001)
echo "txid is: $genesis_input_txid"
echo "creating genesis tx for you"
tx_hex=$($bitcoin_cli gettransaction $genesis_input_txid | jq '.hex'|tr -d '"')
vin_json=$($bitcoin_cli decoderawtransaction $tx_hex | jq '.vout| map(select(.value==2.5001))[0]'|tr -d "[ \n\t]")
vout=$(echo $vin_json|jq '.n')
generate_prevtx_json $vin_json $genesis_input_txid
generate_privkeys_json $genesis_input_address
genesis_raw=$(bitcoin-tx -regtest -create in=$genesis_input_txid:$vout outaddr=$value_alice:${address_alice##B} outaddr=$value_bob:${address_bob##B} load=prevtxs:prevtxs.json load=privatekeys:privatekeys.json sign=ALL)
echo "The raw genesis tx is: $genesis_raw"
echo "Please verify if decoded tx looks ok:"
genesis_decoded=$($bitcoin_cli decoderawtransaction $genesis_raw)
echo $genesis_decoded| jq '.'
genesis_txid=$(echo $genesis_decoded| jq '.txid'|tr -d '"')
echo "Press enter to broadcast transaction, ctrl+c otherwise"
read
echo "Genesis txid is:"
$bitcoin_cli sendrawtransaction $genesis_raw
echo "Mining genesis tx for you"
genesis_block=$($bitcoin_cli generate 1 | jq '.[]'| tr -d '"')
genesis_height=$($bitcoin_cli getblock $genesis_block | jq '.height')
echo "genesis_block is $genesis_block"
echo "genesis_height is $genesis_height"
edit_conf_file $genesis_txid $genesis_height
echo "your conf file was modified accordingly"
echo "DAO setup done"

4
docs/autosetup-regtest-dao/bisq/seed_node Executable file
View file

@ -0,0 +1,4 @@
#!/bin/bash
. ./config.sh
~/bin/bisq/bisq-seednode --baseCurrencyNetwork=BTC_REGTEST --useLocalhostForP2P=true --useDevPrivilegeKeys=true --nodePort=2002 --appName=bisq-BTC_REGTEST_Seed_2002 --daoActivated=true --genesisBlockHeight=$genesis_height --genesisTxId=$genesis_tx --fullDaoNode=$dao --rpcUser=$rpcuser --rpcPassword=$rpcpassword --rpcPort=$rpcport --rpcBlockNotificationPort=$blocknotifyport

7
docs/autosetup-regtest-dao/bitcoin.conf Normal file
View file

@ -0,0 +1,7 @@
regtest=1
txindex=1
rpcuser=bisq
rpcpassword=bisq
blocknotify=./blocknotify %s
server=1

2
docs/autosetup-regtest-dao/blocknotify Executable file
View file

@ -0,0 +1,2 @@
#!/bin/bash
echo $1 | nc -w 1 127.0.0.1 5120

10
docs/autosetup-regtest-dao/clean.sh Executable file
View file

@ -0,0 +1,10 @@
#!/bin/bash
echo "DANGER! This will nuke your bitcoin regtest dir and bisq seed, alice and bob regtest dirs as well!"
echo "Press Enter to continue, otherwise ctrl+c"
read
rm blocks regtest -rf
rm ~/.local/share/bisq-BTC_REGTEST_Seed_2002 -rf
rm ~/.local/share/bisq-BTC_REGTEST_Alice -rf
rm ~/.local/share/bisq-BTC_REGTEST_Bob -rf
sed -r -i 's/dao=.*/dao="false"/' bisq/config.sh
echo "cleaned bitcoind home and bisq seed, alice, bob instances. The conf file for bisq was reset to dao=false"

25
docs/autosetup-regtest-dao/generate_101_blocks.sh Executable file
View file

@ -0,0 +1,25 @@
#!/bin/bash
function is_connected(){
sleep 1
blocks=$(bitcoin-cli -datadir=. -regtest getblockcount)
if [ $? -eq 0 ];then
echo "yes"
else
echo "no"
fi
}
connected=$(is_connected)
until [ "$connected" == "yes" ];do
connected=$(is_connected)
done
blocks=$(bitcoin-cli -datadir=. -regtest getblockcount)
if [ $? -eq 0 ] && [ $blocks -lt 101 ];then
echo "$0: found less blocks then 101, generating ..."
bitcoin-cli -datadir=. -regtest generate 101
echo "$0: done, exiting"
exit 0
fi
echo "$0: nothing to do, exiting"

3
docs/autosetup-regtest-dao/start_bitcoind.sh Executable file
View file

@ -0,0 +1,3 @@
#!/bin/bash
./generate_101_blocks.sh &
bitcoin-qt -datadir=. #-printtoconsole

6
docs/bitcoinj-checkpoint.md Normal file
View file

@ -0,0 +1,6 @@
# How to add a new bitcoinj checkpoint
### Update checkpoint
1. `git checkout https://github.com/bisq-network/bitcoinj.git`
2. `cd tools ; ./build-checkpoints --peer=127.0.0.1 --days=10` (you have to have a local Bitcoin node running)
3. Copy generated `/tools/checkpoints.txt` into `core/src/main/resources/wallet`

74
docs/build.md Normal file
View file

@ -0,0 +1,74 @@
## Building Bisq
1. **Install Git LFS**
Bisq uses Git LFS (Large File Storage) to track certain large binary files. Follow the instructions at https://git-lfs.github.com to install it, then run the following to command to verify the installation:
```sh
git lfs version
```
You should see the version of Git LFS you installed, for example:
```sh
git-lfs/2.10.0 (GitHub; darwin amd64; go 1.13.6)
```
2. **Clone Bisq**
```sh
git clone https://github.com/bisq-network/bisq
cd bisq
```
3. **Pull LFS data**
```sh
git lfs pull
```
4. **Build Bisq**
On macOS and Linux, execute:
```sh
./gradlew build
```
On Windows:
```cmd
gradlew.bat build
```
If you prefer to skip tests to speed up the building process, just append _-x test_ to the previous commands.
### Important notes
1. You do _not_ need to install Gradle to build Bisq. The `gradlew` shell script will install it for you, if necessary.
2. Bisq currently works with JDK 11 only. JDK 12 and above are not supported. You can find out which
version you have with:
```sh
javac -version
```
If you do not have JDK 11 installed, check out scripts in the [scripts](../scripts) directory or download it manually from https://jdk.java.net/archive/.
## Running Bisq
Once Bisq is installed, its executables will be available in the root project directory. Run **Bisq Desktop** as follows:
On macOS and Linux:
```sh
./bisq-desktop
```
On Windows:
```cmd
bisq-desktop.bat
```
## See also
- [Importing Bisq into IntelliJ IDEA](./idea-import.md)
- [Bisq development environment setup guide](./dev-setup.md)

138
docs/dao-setup.md Normal file
View file

@ -0,0 +1,138 @@
# Bisq DAO development setup guide
This guide describes how to setup a Bisq DAO development environment running against a local Bitcoin regtest network.
It assumes you have already configured your development environment following the [dev setup guide](dev-setup.md).
## Configure Bitcoin Core
1. Create/configure the [bitcoin.conf](https://en.bitcoin.it/wiki/Running_Bitcoin#Bitcoin.conf_Configuration_File) file inside the Bitcoin Core [data directory](https://en.bitcoin.it/wiki/Data_directory#Default_Location) as follows.
_Please note that `txindex` triggers a resync of the entire blockchain and be aware if you set that on mainnet it will take a while. Also, extra settings for more security are recommended if you run this in mainnet mode._
Linux:
```
regtest=1
# The default rpcPort for regtest from Bitcoin Core 0.16 and higher is: 18443
# The default rpcPort for testnet is: 18332
# For mainnet: 8332
[regtest]
peerbloomfilters=1
rpcport=18443
server=1
txindex=1
rpcuser=YOUR_USER_NAME
rpcpassword=YOUR_PW
blocknotify=bash ~/.bitcoin/blocknotify %s
```
MacOS:
```
regtest=1
# The default rpcPort for regtest from Bitcoin Core 0.16 and higher is: 18443
# The default rpcPort for testnet is: 18332
# For mainnet: 8332
[regtest]
peerbloomfilters=1
rpcport=18443
server=1
txindex=1
rpcuser=YOUR_USER_NAME
rpcpassword=YOUR_PW
blocknotify=bash ~/Library/Application\ Support/Bitcoin/blocknotify %s
```
Windows:
```
regtest=1
# The default rpcPort for regtest from Bitcoin Core 0.16 and higher is: 18443
# The default rpcPort for testnet is: 18332
# For mainnet: 8332
[regtest]
peerbloomfilters=1
rpcport=18443
server=1
txindex=1
rpcuser=YOUR_USER_NAME
rpcpassword=YOUR_PW
blocknotify="%AppData%\Bitcoin\blocknotify.bat" %s
```
2. Create a `blocknotify` file (`blocknotify.bat` on Windows) inside the Bitcoin Core [data directory](https://en.bitcoin.it/wiki/Data_directory#Default_Location) with the following content.
This defines the ports where a new block event gets forwarded. Bisq will listen on that port and each Bisq node needs to use a different port. You can add or remove ports as needed.
_On Windows, you will need to download and install [ncat](https://nmap.org/ncat/) to be able to use the ncat command._
Linux/MacOS:
```bash
#!/bin/bash
echo $1 | nc -w 1 127.0.0.1 5120
echo $1 | nc -w 1 127.0.0.1 5121
echo $1 | nc -w 1 127.0.0.1 5122
echo $1 | nc -w 1 127.0.0.1 5123
```
Windows:
```batch
echo %1 | ncat -w 1 127.0.0.1 5120
echo %1 | ncat -w 1 127.0.0.1 5121
echo %1 | ncat -w 1 127.0.0.1 5122
echo %1 | ncat -w 1 127.0.0.1 5123
```
## Program arguments for DAO mode
- `--daoActivated`: If set to true it enables the DAO mode. For testnet and regtest it is enabled by default.
- `--genesisBlockHeight`: If set it overrides the hard coded block height of the genesis tx. Set it to your local genesis tx height.
- `--genesisTxId`: If set it overrides the hard coded genesis tx ID. Set it to your local genesis tx ID.
- `--fullDaoNode`: If true it enables full DAO node mode (in contrast to default lite node mode). At least one seed node must be running as a full DAO node to support other lite nodes.
- `--rpcUser`: RPC user as defined in bitcoin.conf
- `--rpcPassword`: RPC pw as defined in bitcoin.conf
- `--rpcPort`: RPC port. For regtest 18443
- `--rpcBlockNotificationPort`: One of the ports defined in the `blocknotify` file.
## Run the application in DAO mode
If you want to run any instance in DAO mode, use the following program arguments.
Full node mode:
`--daoActivated=true --genesisBlockHeight=111 --genesisTxId=30af0050040befd8af25068cc697e418e09c2d8ebd8d411d2240591b9ec203cf --baseCurrencyNetwork=BTC_REGTEST --useDevPrivilegeKeys=true --useLocalhostForP2P=true --nodePort=7777 --appName=bisq-BTC_REGTEST_Alice_dao --fullDaoNode=true --rpcUser=YOUR_USER_NAME --rpcPassword=YOUR_PW --rpcPort=18443 --rpcBlockNotificationPort=5120`
Lite node mode:
Note: At least one seed node must be running as a full DAO node to support other lite nodes.
`--daoActivated=true --genesisBlockHeight=111 --genesisTxId=30af0050040befd8af25068cc697e418e09c2d8ebd8d411d2240591b9ec203cf --baseCurrencyNetwork=BTC_REGTEST --useDevPrivilegeKeys=true --useLocalhostForP2P=true --nodePort=8888 --appName=bisq-BTC_REGTEST_Bob_dao`
_Don't forget to use different rpcBlockNotificationPorts for different full node instances, otherwise only one node will receive the new block event forwarded to that port._
## DAO genesis transaction
### Use the predefined setup
The creation of the genesis tx is a bit cumbersome. To make it easier to get started you can use the [dao-setup.zip](dao-setup.zip) file.
Extract the file and use those data directories for the Bitcoin Core as well as the Alice and Bob instances which are configured to have the genesis tx as defined in the above program arguments (`30af0050040befd8af25068cc697e418e09c2d8ebd8d411d2240591b9ec203cf` at height `111`).
_You need to adjust the path to the `blocknotify` file inside of `bitcoin.conf` before starting Bitcoin Core._
### Setup a custom DAO genesis transaction
To create your own genesis transaction follow these steps:
- Send 2.50010000 BTC from Bitcoin Core to another address inside Bitcoin Core (label it with `Genesis funding address`).
- Go to the send screen and open the coin control feature. Select the labeled transaction output of the address labeled with `Genesis funding address`. Use that as the only input source for the genesis tx.
- Start Alice in full or lite node mode and go to the DAO/Wallet/Receive screen. Copy the BSQ address and use it for one of the receivers of the genesis tx. When pasting into Bitcoin Core remove the `B` prefix - that prefix is marking a BSQ address but technically it is a BTC address.
- Do the same with Bob.
- You send in sum exactly 2.5 BTC to both Alice and Bob. You can choose how to distribute it (e.g. 1 BTC to Alice 1.5 BTC to Bob).
- Set the miner fee so that it is exactly the remaining 0.00010000 BTC. That might be the tricky part as miner fee selection is not very convenient in Bitcoin Core. In worst case if you cannot get the right miner fee you can add the difference to one of the receivers (e.g. send 1.0000234 BTC instead of 1 BTC).
_Note: It is important that there is exactly 2.5 BTC spent entirely as described, otherwise the genesis tx is invalid._

BIN
docs/dao-setup.zip Normal file
View file

Binary file not shown.

10
docs/data-stores.md Normal file
View file

@ -0,0 +1,10 @@
# Data stores
### Update stores
With every release we include the latest snapshot of Mainnet and Testnet data from the P2P network within the client.
* Start your Bisq client on Mainnet and Testnet and let it run until it is fully synced.
* Run [copy_dbs.sh](https://github.com/bisq-network/bisq/blob/master/desktop/package/macosx/copy_dbs.sh) to copy the
required files into the [p2p resources directory](https://github.com/bisq-network/bisq/blob/master/p2p/src/main/resources).
* To add a new trade statistic snapshot just add it to the list of trade statistic snapshots in https://github.com/bisq-network/bisq/blob/0345c795e2c227d827a1f239a323dda1250f4e69/common/src/main/java/bisq/common/app/Version.java#L40

97
docs/dev-setup.md Normal file
View file

@ -0,0 +1,97 @@
# Bisq dev setup guide
This guide describes how to set up a complete Bisq development environment running against a local Bitcoin regtest network. You'll run your own Bisq seed node, arbitration and trading instances in order to allow for end-to-end development and testing.
## Prerequisites
Follow the instructions in [build.md](build.md) to build Bisq from source, and it is also recommended to follow the instructions in [idea-import.md](idea-import.md) to be able to run everything from within IntelliJ IDEA. Please also read and follow the instructions in [CONTRIBUTING.md](../CONTRIBUTING.md) prior to submitting any pull requests.
## Overview
When developing Bisq, you usually want to use Bitcoin in **regtest** mode and do all networking on **localhost** instead of using the Tor network. Typically, you'll want an environment set up with the following components:
- Bitcoin Core or bitcoind in regtest mode
- A local Bisq seed node
- A local Bisq arbitrator & mediator instance
- 2 local Bisq trading instances (BTC buyer and BTC seller for executing a trade)
You'll set up each of these in the steps that follow.
## Run Bitcoin Core (or bitcoind) in regtest mode
The regtest mode operates a local Bitcoin network on your computer. This environment is ideally suited for testing because you are able to create blocks on demand (no need to wait for confirmations) and you don't need to download the blockchain. By creating blocks you act like a miner and you can generate new Bitcoin.
You can find more information about the Bitcoin regtest mode [here](https://bitcoin.org/en/developer-examples#regtest-mode).
Navigate to the [bitcoin.conf](https://en.bitcoin.it/wiki/Running_Bitcoin#Bitcoin.conf_Configuration_File) file and set `regtest=1` and `peerbloomfilters=1`, or add `-regtest -peerbloomfilters=1` as a program arguments when starting Bitcoin Core.
At first startup you need to create 101 blocks using the command `generatetoaddress 101 address`* from the terminal inside Bitcoin Core, where `address` value could be obtained with the command `getnewaddress`. 101 blocks are required because of the coin maturity (100 blocks) so you need one more to have at least 50 BTC available for spending.
Example:
generatetoaddress 101 bcrt1qhqn0t94uc269szakr4ez0zh7erdd6tlm4pv6mg
Later you can create new blocks with `generatetoaddress 1 address`*.
*If you are using Bitcoin Core v.0.18 or less, use instead `generate 1`.
## Understand Bisq P2P network options
For the local P2P network we prefer to use `localhost`, not the Tor network as it is much faster. But if needed you can combine any of the following combinations of Bitcoin network mode and P2P network mode:
- localhost + regtest
- localhost + testnet
- localhost + mainnet
- Tor + regtest
- Tor + testnet
- Tor + mainnet
## Understand Bisq program arguments
There are several program arguments required to run in development mode.
Here is an overview:
- `--baseCurrencyNetwork`: The BTC network to use. Possible values are: `BTC_REGTEST`, `BTC_TESTNET`, `BTC_MAINNET` (default)
- `--useLocalhostForP2P`: Uses localhost instead of Tor for Bisq P2P network
- `--nodePort`: Port number for localhost mode. For seed nodes there is a convention with the last digit is marking the network type and there is a list of hard coded seed nodes addresses (see: `DefaultSeedNodeAddresses.java`). For regtest: 2002 and 3002. For testnet 2001, 3001 and 4001 and for mainnet: 2000, 3000 and 4000. For normal nodes the port can be chosen freely.
- `--useDevPrivilegeKeys`: Important for dev testing to allow the developer key for arbitration registration
- `--appName`: Custom application name which is used for the data directory. It is important to separate your nodes to not interfere. If not set, it uses the default `Bisq` directory.
## Run Bisq seednode
For localhost/regtest mode run the `SeedNodeMain` class or `./bisq-seednode` script in the root project dir with following program arguments:
--baseCurrencyNetwork=BTC_REGTEST --useLocalhostForP2P=true --useDevPrivilegeKeys=true --nodePort=2002 --appName=bisq-BTC_REGTEST_Seed_2002
### Run Bisq arbitrator/mediator instance
For localhost/regtest mode run the `BisqAppMain` class or `./bisq-desktop` script in the root project dir with following program arguments:
--baseCurrencyNetwork=BTC_REGTEST --useLocalhostForP2P=true --useDevPrivilegeKeys=true --nodePort=4444 --appName=bisq-BTC_REGTEST_arbitrator
Once it has started up go to `Account` and click `CMD +n`. This will open a new tab for `Arbitration registration`. Select the tab and you will see a popup with a pre-filled private key. That is the developer private key (which is only valid if `--useDevPrivilegeKeys` is set) which allows you to register a new arbitrator. Follow the next screen and complete registration.
Next you have to register a mediator as well. Click `CMD + d`. This will open a new tab for `Mediator registration`. Follow the same steps as for the arbitrator registration before. Registration of legacy arbitrators was done with `CMD +n`. It is not needed anymore so we refer with the term arbitrator to the new arbitrator (or refund agent).
_Note: You need only register once but if you have shut down all nodes (including seed node) you need to start up the arbitrator again after you start the seed node so the arbitrator re-publishes his data to the P2P network. After it has started up you can close it again. You cannot trade without having an arbitrator available._
### Run two Bisq trade instances
For localhost/regtest mode run the `BisqAppMain` class or `./bisq-desktop` script in the root project dir with following program arguments:
--baseCurrencyNetwork=BTC_REGTEST --useLocalhostForP2P=true --useDevPrivilegeKeys=true --nodePort=5555 --appName=bisq-BTC_REGTEST_Alice
and
--baseCurrencyNetwork=BTC_REGTEST --useLocalhostForP2P=true --useDevPrivilegeKeys=true --nodePort=6666 --appName=bisq-BTC_REGTEST_Bob
At this point you can now perform trades between Alice and Bob using your local regtest environment and test from both the buyer's and seller's perspective. You can also open disputes with `cmd+o` and see how the arbitration system works (run the arbitrator in that case as well).
_Remember to generate a new block in the Bitcoin Core console after taking an offer using the command `generatetoaddress 1 address` to trigger a block confirmation._

BIN
docs/edit_configurations.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 28 KiB

21
docs/idea-import.md Normal file
View file

@ -0,0 +1,21 @@
# Importing Bisq into IntelliJ IDEA
Most Bisq contributors use IDEA for development. The following instructions have been tested on IDEA 2021.1.
1. Follow the instructions in [build.md](build.md) to clone and build Bisq at the command line.
1. Open IDEA
1. Go to `File -> Settings -> Build, Execution, Deployment -> Compiler -> Annotation Processors` and check the `Enable annotation processing` option to enable processing of Lombok annotations (Lombok plugin installed by default since v2020.3)
1. Go to `File -> New -> Project from Existing Sources...` and then select the main Bisq folder to load automatically the related Gradle project
1. If you did not yet setup JDK11 in IntelliJ, go to `File-> Project Structure -> Project` and under the `Project SDK` option locate your JDK11 folder
1. Select JDK 11 for Gradle as well. Go to `File -> Settings -> Build, Execution, Deployment -> Build Tools -> Gradle` and select the JDK11 location for the Gradle JVM value
1. Go to `Build -> Build Project`. Everything should build cleanly
1. Go to `Run > Edit Configurations... -> Plus (+) icon on the top left -> Application` anf then fill the requested fields as shown below, while using as CLI arguments one of those listed in [dev-setup.md](dev-setup.md):
![edit_configurations.png](edit_configurations.png)
9. Now you should be able to run Bisq by clicking on the _Play_ button or via `Run -> Run 'Bisq Desktop'`
10. If you want to debug the application and execute breakpoints, use `Run -> Debug 'Bisq Desktop'`
> TIP: If you encounter compilation errors in IDEA related to the `protobuf.*` classes, it is probably because you didn't build Bisq at the command line as instructed above. You need to run the `generateProto` task in the `other` project. You can do this via the Gradle tool window in IDEA, or you can do it the command line with `./gradlew :other:generateProto`. Once you've done that, run `Build -> Build Project` again and you should have no errors.
>
> If this does not solve the issue, try to execute `./gradlew clean` and then rebuild the project again.

242
docs/release-process.md Normal file
View file

@ -0,0 +1,242 @@
# Release Process
* Update translations [translation-process.md](translation-process.md#synchronising-translations).
* Update data stores [data-stores.md](data-stores.md#update-stores).
* Update bitcoinj checkpoint [bitcoinj-checkpoint](bitcoinj-checkpoint.md#update-checkpoint).
* Write release notes (see below).
* Webpage (Prepare PR)
* Update version number in:
* [_config.yml](https://github.com/bisq-network/bisq-website/blob/master/_config.yml)
* Update currency list
in [market_currency_selector.html](https://github.com/bisq-network/bisq-website/blob/master/_includes/market_currency_selector.html) (
use [MarketsPrintTool](https://github.com/bisq-network/bisq/blob/master/desktop/src/test/java/bisq/desktop/MarketsPrintTool.java)
to create HTML content).
### Bisq maintainers, suggestion for writing release notes
To be able to create release notes before you make the final release tag, you can temporarily create a local tag and
remove it afterwards again.
git tag v(new version, e.g. 0.9.4) #create tag
git tag -d v(new version, e.g. 0.9.4) #delete tag
Write release notes. git shortlog helps a lot, for example:
git shortlog --no-merges v(current version, e.g. 0.9.3)..v(new version, e.g. 0.9.4)
Generate list of authors:
git log --format='- %aN' v(current version, e.g. 0.9.3)..v(new version, e.g. 0.9.4) | sort -fiu
1. Prepare the release notes with major changes from user perspective.
2. Prepare a short version of the release notes for the in-app update popup
### Basic preparations
For releasing a new Bisq version you'll need Linux, Windows and macOS. You can use a virtualization solution
like [VirtualBox](https://www.virtualbox.org/wiki/Downloads) for this purpose.
#### VirtualBox recommended configuration
Although performance of VMs might vary based on your hardware configuration following setup works pretty well on macOS.
Use VirtualBox > 6.1 with following configuration:
* System > Motherboard > Base Memory: 4096 MB
* System > Processor > Processor(s): 2 CPUs
* System > Processor > Execution Cap: 90%
* Display > Screen > Video Memory: 128 MB
* Display > Screen > Scale Factor: 200%
* Display > Screen > HiDPI Support: Use unscaled HiDPI Output (checked)
* Display > Screen > Acceleration: Enable 3D acceleration (checked)
##### Windows VM
* Windows 10 64bit
* Recommended virtual disk size: 55 GB
##### Linux VM
* Ubuntu 16.04.4 64bit
* Recommended virtual disk size: 25 GB
##### macOS VM
* macOS X 10.11 (El Capitan) 64bit
* Recommended virtual disk size: 40 GB
#### For every OS
* Install latest security updates
#### For Windows
* Update AntiVirus Software and virus definitions
* Install [WiX toolset](https://wixtoolset.org/releases/)
* Run full AV system scan
### Build release
#### macOS
To be able to generate a signed and notarized binary you have to have an Apple developer account and create the required
certificate and provisioning file before running the build.
1. Make sure all version numbers are updated (update version variables and
run [replace_version_number.sh](https://github.com/bisq-network/bisq/blob/master/desktop/package/macosx/replace_version_number.sh))
.
2. Set environment variables to ~/.profile file or the like... (one time effort)
* `BISQ_GPG_USER`: e.g. export BISQ_GPG_USER=manfred@bitsquare.io
* `BISQ_SHARED_FOLDER`: shared folder that is used between your VM host and client system
* `BISQ_PACKAGE_SIGNING_IDENTITY`: e.g. "Developer ID Application: Christoph Atteneder (WQT93T6D6C)"
* `BISQ_PRIMARY_BUNDLE_ID`: e.g. "network.bisq.CAT"
* `BISQ_PACKAGE_NOTARIZATION_AC_USERNAME`: your Apple developer email address
* `BISQ_PACKAGE_NOTARIZATION_ASC_PROVIDER`: Your developer ID (e.g. WQT93T6D6C)
3. Run `./gradlew --console=plain packageInstallers`
Build output expected in shared folder:
1. `Bisq-${NEW_VERSION}.dmg` macOS notarized and signed installer
2. `desktop-${NEW_VERSION}-all.jar.SHA-256` sha256 sum of fat jar
3. `jar-lib-for-raspberry-pi-${NEW_VERSION}.zip` Jar libraries for Raspberry Pi
* Before building the other binaries install the generated Bisq app on macOS and verify that everything works as
expected.
#### Linux
1. Checkout the release tag in your VM
2. Set environment variables to ~/.profile file or the like... (one time effort)
* `BISQ_SHARED_FOLDER`: shared folder that is used between your VM host and client system
3. Run `./gradlew --console=plain packageInstallers`
Build output expected:
1. `bisq_${NEW_VERSION}-1_amd64.deb` package for distributions that derive from Debian
2. `bisq-${NEW_VERSION}-1.x86_64.rpm` package for distributions that derive from Redhat based distros
3. `desktop-${NEW_VERSION}-all.jar.SHA-256` sha256 sum of fat jar
* Install and run generated package
#### Windows
To be able to generate a signed binary you have to apply and install a developer certificate before running the build.
1. Checkout the release tag in your VM
2. Set environment variables to ~/.profile file or the like... (one time effort)
* `BISQ_SHARED_FOLDER`: shared folder that is used between your VM host and client system
3. Run `./gradlew --console=plain packageInstallers`
Build output expected:
1. `Bisq-${NEW_VERSION}.exe` Windows signed installer
2. `desktop-${NEW_VERSION}-all.jar.SHA-256` sha256 sum of fat jar
* Install and run generated package
### Sign release on macOS
* Run [finalize.sh](https://github.com/bisq-network/bisq/blob/master/desktop/package/macosx/finalize.sh)
Build output expected:
1. `F379A1C6.asc` Sig key of Manfred Karrer
2. `5BC5ED73.asc` Sig key of Chris Beams
3. `29CDFD3B.asc`Sig key of Christoph Atteneder
4. `signingkey.asc` Fingerprint of key that was used for these builds
5. `Bisq-${NEW_VERSION}.dmg` macOS installer
6. `Bisq-${NEW_VERSION}.dmg.asc` Signature for macOS installer
7. `Bisq-64bit-${NEW_VERSION}.deb` Debian package
8. `Bisq-64bit-${NEW_VERSION}.deb.asc` Signature for Debian package
9. `Bisq-64bit-${NEW_VERSION}.rpm` Redhat based distro package
10. `Bisq-64bit-${NEW_VERSION}.rpm.asc` Signature for Redhat based distro package
11. `Bisq-64bit-${NEW_VERSION}.exe` Windows installer
12. `Bisq-64bit-${NEW_VERSION}.exe.asc` Signature for Windows installer
* Run a AV scan over all files on the Windows VM where the files got copied over.
### Final test
* Make at least one mainnet test trade with some exotic currency to not interfere with real traders.
### Tag and push release to master
If all was successful:
* commit changes of new version number (update version number for release of e.g. v1.5.0)
* create tag for the release
```
git tag -s v(new version, e.g. 1.5.0) -m"Release v(new version, e.g. 1.5.0)"
```
* Revert back to SNAPSHOT where necessary (change version variable (e.g. 1.5.0) in shell
script [insert_snapshot_version.sh](https://github.com/bisq-network/bisq/blob/master/desktop/package/macosx/insert_snapshot_version.sh)
and run it) and commit these changes.
* Push all commits to master including the new tag
```
git push --tags origin master
```
### GitHub
#### Upload preparations
* Check the fingerprint of the pgp key which was used for signing in signingkey.asc (e.g. 29CDFD3B for Christoph
Atteneder)
* Add all files including signingkey.asc and the gpg pub keys to GitHub release page
* Check all uploaded files with [virustotal.com](https://www.virustotal.com)
* Select the release tag as the source for the GitHub release.
* Release on GitHub
#### Post GitHub release
* Apply “A newer version is already available! Please don’t use this version anymore.” to old GitHub releases.
* Merge the webpage PR and check if they got deployed properly.
* Start the Alert sender app (CMD + M) remove the old version and send the update message. Check the checkbox for
update, set the version number (e.g. 0.9.4) and add the short version of the release notes.
* After sending the Update message leave it running for about 1 minute to give time for good propagation.
* Make a backup of that alert sender app data directory
* To support source code signature verification for Arch Linux download `Source code (tar.gz)`, sign it and upload
signature.
```
# sign source code bundle
gpg --digest-algo SHA256 --local-user $BISQ_GPG_USER --output bisq-${NEW_VERSION}.tar.gz.asc --detach-sig --armor bisq-${NEW_VERSION}.tar.gz
# verify signature of source code bundle
gpg --digest-algo SHA256 --verify bisq-${NEW_VERSION}.tar.gz{.asc*,}
```
### Announce the release
* Forum
* Keybase (#general channel)
* Twitter
* Optionally reddit /r/Bisq
* Notify @freimair so that he can start
updating [the Arch User Repository](https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=bisq-git)
* Celebrate

81
docs/testing.md Normal file
View file

@ -0,0 +1,81 @@
# Bisq Testing Guide
This guide describes the testing process performed prior to each release.
## Prerequisites
In order to take part in the testing process, you will need to do the following:
- Build Bisq from source (see [build.md](build.md))
- Setup a development/testing environment (see [Makefile](../Makefile) or [dev-setup.md](dev-setup.md))
- Request access to [TestPad](https://bisq.ontestpad.com) (our test management tool)
## Communication Channels
If you would like to discuss and/or contribute to Bisq's testing effort, join us in the #testing channel within the [Bisq Keybase team](https://keybase.io/team/bisq).
Here you could also request access to TestPad (https://bisq.ontestpad.com).
## Compensation
Testing activities are eligible for [compensation](https://docs.bisq.network/dao/phase-zero.html#how-to-request-compensation).
When submitting a compensation request, please include links to artifacts on TestPad (results/reports) indicating the activities that were performed (e.g. tests that were executed), as well as any bugs that were discovered and entered as a result of testing.
## Testing Process
[TestPad](https://bisq.ontestpad.com) is used to manage and track the manual testing process.
For specific usage or functionality of TestPad, please see the flash card introduction within TestPad.
### Definitions
Some definitions within the context of TestPad and how they apply to our specific testing process:
- **Project:** Defines a particular testing scope with relevant tests.
- **Script:** Each script is a collection of related tests that are intended to be used to test a particular component.
- **Folder:** Defines a group of scripts for each release.
### Test Structure
Tests are written using Behaviour-Driven Development (BDD) style syntax (given/when/then).
- **Given:** This states the preconditions that are assumed for the test. It is not a test step (one that requires a result to be recorded), but instead you must ensure the preconditions are satisfied in order to perform the test.
- **When:** This states the actions to be performed for the test. This also does not require a result to be recorded.
- **Then:** This states the expected results of the test. This requires a result to be recorded.
### Testing Workflow
Once logged in to TestPad, select the `Desktop Client` project from the left navigation menu.
Each upcoming release will have a new folder created with applicable scripts that need to be executed.
#### Executing a Script
Test runs allow for tracking the results of test execution. Each script may have several test runs created in order to perform the tests on different environments (e.g. operating systems) and assigned to different people. An overview of all test runs for the release can be observed from the main project view, which allows you to quickly find test runs assigned to yourself.
To execute a test run:
1. Open the script to be executed.
1. Hover over the applicable test run column and select the play button to start executing the test run.
1. Follow the script and perform each test.
- Select a status for each test. Select from one of the following statuses:
- **Pass:** the test has passed successfully.
- **Fail:** there is an issue (defect) related to the test.
- **Blocked:** the test cannot be performed for a particular reason.
- **Query:** you are unsure about the test and require further information.
- **Exclude:** the test does not need to be performed for a particular reason.
- If necessary, use the `Comments` field to add any comments, notes and actual test results. This is especially beneficial to provide details if a test did not pass.
- If applicable, link an existing or create a new issue (defect) if it was found during the test run execution.
### Creating Issues
When creating issues, it is important to provide sufficient information describing the problem encountered. In addition to a clear and concise description, this may include attaching screenshots or log files if necessary so the assigned developer can identify and resolve the issue.
### Testing Tips
- **Test from a new users perspective.** In addition to looking for obvious errors, be on the lookout for any usability or workflow concerns.
- **Reset the "don't show again" flags.** This will allow you to verify the popup messages are valid and appropriate.

122
docs/tor-upgrade.md Normal file
View file

@ -0,0 +1,122 @@
# Tor upgrade in Bisq
This guide describes the steps necessary to upgrade the tor dependencies used by Bisq.
## Background
Bisq uses two libraries for tor: [netlayer][1] and [tor-binary][2].
As per the project's authors, `netlayer` is _"essentially a wrapper around the official Tor releases, pre-packaged for
easy use and convenient integration into Kotlin/Java projects"_.
Similarly, `tor-binary` is _"[the] Tor binary packaged in a way that can be used for java projects"_. The project
unpacks the tor browser binaries to extract and repackage the tor binaries themselves.
Therefore, upgrading tor in Bisq comes down to upgrading these two artefacts.
## Upgrade steps
### 1. Decide if upgrade necessary
- Find out which tor version Bisq currently uses
- Find out the current `netlayer` version (see `netlayerVersion` in `bisq/build.gradle`)
- Find that release on the project's [releases page][3]
- The release description says which tor version it includes
- Find out the latest available tor release
- See the [official tor changelog][4]
### 2. Update `tor-binary`
During this update, you will need to keep track of:
- the new tor browser version
- the new tor binary version
Create a PR for the `master` branch of [tor-binary][2] with the following changes:
- Decide which tor browser version contains the desired tor binary version
- The official tor browser releases are here: https://dist.torproject.org/torbrowser/
- For the chosen tor browser version, get the list of SHA256 checksums and its signature
- For example, for tor browser 10.0.12:
- https://dist.torproject.org/torbrowser/10.0.12/sha256sums-signed-build.txt
- https://dist.torproject.org/torbrowser/10.0.12/sha256sums-signed-build.txt.asc
- Verify the signature of the checksums list (see [instructions][5])
- Update the `tor-binary` checksums
- For each file present in `tor-binary/tor-binary-resources/checksums`:
- Rename the file such that it reflects the new tor browser version, but preserves the naming scheme
- Update the contents of the file with the corresponding SHA256 checksum from the list
- Update `torbrowser.version` to the new tor browser version in:
- `tor-binary/build.xml`
- `tor-binary/pom.xml`
- Update `version` to the new tor binary version in:
- `tor-binary/pom.xml`
- `tor-binary-geoip/pom.xml`
- `tor-binary-linux32/pom.xml`
- `tor-binary-linux64/pom.xml`
- `tor-binary-macos/pom.xml`
- `tor-binary-windows/pom.xml`
- `tor-binary-resources/pom.xml`
- Run `mvn install`
- If it completes successfully, then the artefact is correctly configured
Only the files listed above should be part of the PR. The last step will generate a few extra artefacts (for
example in `tor-binary-resources/src/main/resources`), but these should NOT be committed.
Once the PR is merged, make a note of the commit ID in the `master` branch (for example `a4b868a`), as it will be needed
next.
### 3. Update `netlayer`
Create a PR for the `externaltor` branch of [netlayer][1] with the following changes:
- In `netlayer/pom.xml`:
- Update `tor-binary.version` to the `tor-binary` commit ID from above (e.g. `a4b868a`)
- Bump `version`, representing the `netlayer` artefact version, in:
- `netlayer/pom.xml`
- `netlayer/tor/pom.xml`
- `netlayer/tor.external/pom.xml`
- `netlayer/tor.native/pom.xml`
Once the PR is merged, make a note of the commit ID in the `externaltor` branch (for example `32779ac`), as it will be
needed next.
Create a tag for the new artefact version, having the new tor binary version as description, for example:
```
# Create tag locally for new netlayer release, on the externaltor branch
git tag -s 0.7.0 -m"tor 0.4.5.6"
# Push it to netlayer repo
git push origin 0.7.0
```
### 4. Update dependency in Bisq
Create a Bisq PR with the following changes:
- In `bisq/build.gradle` update `netlayerVersion` to the `netlayer` commit ID from above
- Update the gradle dependency checksums
- See instructions in `bisq/gradle/witness/gradle-witness.gradle`
## Credits
Thanks to freimair, JesusMcCloud, mrosseel, sschuberth and cedricwalter for their work on the original
[tor-binary](https://github.com/JesusMcCloud/tor-binary) and [netlayer](https://github.com/JesusMcCloud/netlayer) repos.
[1]: https://github.com/bisq-network/netlayer "netlayer"
[2]: https://github.com/bisq-network/tor-binary "tor-binary"
[3]: https://github.com/bisq-network/netlayer/releases "netlayer releases"
[4]: https://gitweb.torproject.org/tor.git/plain/ChangeLog "tor changelog"
[5]: https://support.torproject.org/tbb/how-to-verify-signature/ "verify tor signature"

50
docs/translation-process.md Normal file
View file

@ -0,0 +1,50 @@
# Translation Process
### Overview
Bisq is offered in multiple languages. Translations are managed with Transifex online software.
User facing texts **must not** be hardcoded in the source code files.
English is the base language for translations.
### Adding or changing English texts
Being a base language English is managed directly in the project.
Edit `core/src/main/resources/i18n/displayStrings.properties` to add or modify English texts.
Mind the chapters. Fit your entry properly.
Once your changes get merged the Transifex will sync itself with GitHub.
However, **do not** edit files for other languages. They are synced from Transifex.
### Adding or changing texts in other languages (non-English)
All translations are managed with [Transifex](https://www.transifex.com/).
Sign up, find `bisq-desktop` project, and join the team.
Once accepted, you will be able to edit translations.
The entry must exist in English to be available for translation.
To make translations effective in the project you need to install the Transifex client and run the script to pull the updates.
This is described below.
### Installing the Transifex client command-line tool
You'll find a detailed guide [how to install the Transifex client](https://docs.transifex.com/client/installing-the-client) on the Transifex page.
The Transifex Bisq project config file is included as part of the repository. It can be found at `core/.tx/config`.
### Synchronising translations
We've prepared a script to update the translation files with the Transifex client command-line tool.
* Run [update_translations.sh](https://github.com/bisq-network/bisq/blob/master/core/update_translations.sh)
Synchronization output expected:
* All translation files in [i18n directory](https://github.com/bisq-network/bisq/blob/master/core/src/main/resources/i18n) have been updated.
Go over the changes if there are any obvious issues (Transifex had once a problem which caused a rewrite of certain keys)
and commit and push them to master.