From eb88dcae672f50a78ffcdbfcb9716feb414af1b1 Mon Sep 17 00:00:00 2001 From: Adam Gibson Date: Sat, 19 Aug 2017 14:49:29 +0300 Subject: [PATCH] update docs with more installation info --- README.md | 28 ++++++++++++++++++++++++---- docs/INSTALL.md | 7 ++----- docs/SEGWIT-UPGRADE.md | 10 ++++++---- docs/USAGE.md | 24 ++++++++++++++++++++++-- install.sh | 6 +++--- 5 files changed, 57 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index b199aa2..afea65c 100644 --- a/README.md +++ b/README.md @@ -3,19 +3,39 @@ Joinmarket refactored to separate client and backend operations **NOTE: To use current Joinmarket, use the [latest release](https://github.com/AdamISZ/joinmarket-clientserver/releases). -The master branch is upgraded for segwit and to be used only for testing until the next release.** +The master branch is upgraded for segwit and to be used only for that; a new release will be made shortly.** ### Quickstart -You need to follow the [install guide](docs/INSTALL.md). +**You need Bitcoin Core to use; get it running first.** -The above document will point you to the [segwit upgrade guide](docs/SEGWIT-UPGRADE.md) if you need to update your wallet. +Once you've downloaded this repo, either as a zip file, and extracted it, or via `git clone`: + + ./install.sh + (follow instructions on screen; provide sudo password when prompted) + source jmvenv/bin/activate + cd scripts + +You should now be able to run the scripts like `python wallet-tool.py` etc., just as you did in the previous Joinmarket version. + +Alternative to this "quickstart": follow the [install guide](docs/INSTALL.md). + +### Upgrade for segwit + +See the [segwit upgrade guide](docs/SEGWIT-UPGRADE.md) if you need to update your wallet. + +### Usage If you are new, follow and read the links in the [usage guide](docs/USAGE.md). If you are not new to Joinmarket, the notes in the [scripts readme](scripts/README.md) help to understand what has and hasn't changed about the scripts. -There is a joinmarket-qt GUI included but it's not yet ready for the new segwit version. +### Joinmarket-Qt + +Provides single join and multi-join/tumbler functionality (i.e. "Taker") only, in a GUI. + +Binaries that are built and signed will be in the Releases page. To run the script +`joinmarket-qt.py` from the command line, pay attention to the note [here](https://github.com/AdamISZ/electrum-joinmarket-plugin#a-note-on-pyqt4-and-virtualenv). ### Notes on architectural changes (can be ignored) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index f2e8262..a1ab0bf 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -20,11 +20,6 @@ or `git fetch; git checkout tags/` for a specific tagged release, then process as described below. This will only work if the latest commit, or the tag, is actually newer in version number, than what was there already. -Lastly, on compatibility, it's considered the responsibility of the developer(s) to -ensure that the code here is always compatible with that in the [main](https://github.com/Joinmarket-Org/joinmarket) -repo, so you should always be able to run the latest version and successfully transact -with other participants in the Joinmarket pit. - ### Installation on Linux To install everything (client and server), install these packages: @@ -65,6 +60,8 @@ Install this repo: If you have installed this "full" version of the client, you can use it with the command line scripts as explained in the [scripts README](https://github.com/AdamISZ/joinmarket-clientserver/tree/master/scripts). +Alternative/custom installation: + #### Installing the daemon separately Just do diff --git a/docs/SEGWIT-UPGRADE.md b/docs/SEGWIT-UPGRADE.md index da71087..abdd330 100644 --- a/docs/SEGWIT-UPGRADE.md +++ b/docs/SEGWIT-UPGRADE.md @@ -5,6 +5,8 @@ a wallet with segwit addresses. These addresses are P2SH (start with '3' on main note they are *not* multisig, however, they are yours only (technically we are using address type P2SH/P2WPKH). +(Some parts of this are a repeat of what's in the [usage guide](USAGE.md)). + #### If you don't have an existing Joinmarket wallet: You can go into the `scripts/` directory, which contains the `wallet-tool.py` script, @@ -20,7 +22,7 @@ Also, the BIP32 paths are different, see the bottom of this page for some detail Migrating coins to this new-style wallet can be done in these steps: -* Install this new version (0.3.0+), see [here](INSTALL.md) +* Install this new version (0.3.0+), use "Quickstart" from the [readme](../README.md) or see [here](INSTALL.md) * Generate a new wallet; go into the `scripts/` directory and do the same as before: @@ -47,12 +49,12 @@ will find the old wallet. Whether using method (1) or (2), the next step is the Use `python sendpayment.py -N 0 -m [mixdepth] oldwalletname 0 destaddr` to send coins from your old wallet, mixdepth 0, into the new one you've created, with a sweep from that -mixdepth. The -N 0 means using direct-send, i.e. not using joinmarket/IRC, so it's -the cheapest/most convenient. Don't forget to reset `tx_fees` in your joinmarket.cfg +mixdepth. The -N 0 means using direct-send, i.e. not using joinmarket/IRC. +Don't forget to reset `tx_fees` in your joinmarket.cfg if you want to adjust the projected fee. If you've used (2), then delete the line `segwit = false` from joinmarket.cfg, and -reload the new wallet with python wallet-tool.py newwalletname.json +reload the new wallet with `python wallet-tool.py newwalletname.json` Once you're sure it's working you can repeat this process for any number of mixdepths for which you want to transfer coins. diff --git a/docs/USAGE.md b/docs/USAGE.md index e9465b8..2ab0181 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -1,4 +1,7 @@ -### Zeroth step: configuring Bitcoin Core +(You have either followed the Quick Install on the readme (`./install.sh`), or have +followed a manual installation as per [here](INSTALL.md)). + +### Zeroth step: configuring for Bitcoin Core Until such time as we have a better solution for a light client, Joinmarket only realistically supports use with Bitcoin Core to connect to the Bitcoin network. @@ -7,8 +10,23 @@ The node *can* be pruned. **Use with another interface to the blockchain should be considered highly experimental (and in most cases it doesn't really work, as well as being terrible for privacy). It is not supported at this time.** -For notes on how to configure your Core node for use with Joinmarket, read [here](https://github.com/JoinMarket-Org/joinmarket/wiki/Running-JoinMarket-with-Bitcoin-Core-full-node#requirements--how-to). +Configuring Joinmarket for Core is now drastically reduced, since there is no longer any `walletnotify` used. + +First thing to do: in `scripts/`, run: + + python wallet-tool.py generate +This *should* quit with an error, because the rpc is not configured. Open the newly created file `joinmarket.cfg`, +and edit: + + [BLOCKCHAIN] + rpc_user = yourusername-as-in-bitcoin.conf + rpc_password = yourpassword-as-in-bitcoin.conf + rpc_host = localhost #default usually correct + rpc_port = 18332 # default for mainnet + +Then retry the same `generate` command; it should now not error (see below). +If you still get rpc connection errors, make sure you can connect to your Core node using the command line first. ### First step: make a Joinmarket wallet @@ -28,6 +46,8 @@ Read [this section](https://github.com/JoinMarket-Org/joinmarket/wiki/Using-the- in the previously linked page. Don't neglect the point mentioned that, if you are planning to do your own coinjoins (act as "Taker", you must fund multiple different addresses to avoid inconvenience in future. For Makers, that's not necessary. +If you are upgrading from non-Segwit JM, you'll want to read this [upgrade guide](SEGWIT-UPGRADE.md). + ### Third step: Try out a coinjoin To try doing one coinjoin, use the `sendpayment.py` script. See [here](https://github.com/JoinMarket-Org/joinmarket/wiki/Sending-payments-with-CoinJoin#send-payment) diff --git a/install.sh b/install.sh index 8077bcd..8bf286a 100755 --- a/install.sh +++ b/install.sh @@ -103,8 +103,8 @@ clear if ! mkdir venv; then echo "virtualenv directory already exists; assuming valid." fi -virtualenv venv -source venv/bin/activate +virtualenv jmvenv +source jmvenv/bin/activate #required for older pips, e.g. on Ubuntu 14.04 pip install --upgrade setuptools #Doing manually instead of as in setupall.py @@ -125,7 +125,7 @@ cd .. echo " JOINMARKET SUCCESSFULLY INSTALLED. BEFORE RUNNING SCRIPTS, TYPE: - source venv/bin/activate + source jmvenv/bin/activate FROM THIS DIRECTORY, TO ACTIVATE THE VIRTUALENV. " read -p "PRESS ENTER TO EXIT SCRIPT. "