diff --git a/README.md b/README.md index abfc1fdd..34834913 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,8 @@ Taproot as soon as possible, for enhanced privacy. ## Usage +TL;DR: if you just want to quickly try Liana, check out [the guide](doc/TRY.md)! + As a Bitcoin wallet, Liana needs to be able to connect to the Bitcoin network. The software has been developed such as multiple ways to connect to the Bitcoin network may be available. However for now only the connection through `bitcoind` is implemented. @@ -37,9 +39,11 @@ your machine yet, you can download it [there](https://bitcoincore.org/en/downloa ### Installing the software -TODO: download links +The recommended installation method for regular users is to download a release. If you prefer to +build the project from source, see [`doc/BUILD.md`](doc/BUILD.md). + +TODO: instructions for downloading a release and verifying the signatures. -TODO: link to a longer-form document in the doc/ folder containing the different build methods. ### Setting up a wallet diff --git a/doc/BUILD.md b/doc/BUILD.md new file mode 100644 index 00000000..914a70f4 --- /dev/null +++ b/doc/BUILD.md @@ -0,0 +1,89 @@ +# Building Liana + +We use [Cargo](https://doc.rust-lang.org/stable/cargo/), the ubiquitous Rust package manager. +Cargo takes care of downloading and compiling the projects dependencies, as well as compiling the +project itself. Dependencies are specified in a [`Cargo.toml`](../Cargo.toml) file at the root of +this repository. They are pinned in a [`Cargo.lock`](../Cargo.lock) file at the same place. + +We take security very seriously, and toolchain is a big part of that. We are moderatly conservative +with dependencies and aim to target reasonable compiler versions that have had time to mature (ie +that had the chance to be reviewed and distributed by third parties, as well as tested by the +community). The minimum supported Rust version for `lianad` currently is `1.48`, that is the +version of [`rustc` shipped in Debian stable](https://packages.debian.org/stable/rustc). (It is also +inferior to the latest version of `rustc` supported by +[`mrustc`](https://github.com/thepowersgang/mrustc/) supported at the time of writing, `1.54`). + + +## Getting `Cargo` + +### Through your system package manager + +Most package managers distribute a version of `Cargo` able to build this project. For instance on +Debian-based systems (as root): +``` +apt update && apt install cargo +``` + +### By manually downloading the latest stable version + +The ["other installation +methods"](https://forge.rust-lang.org/infra/other-installation-methods.html#standalone-installers) +page of the Rust website contains a list of archives for different architectures, along with +signatures made with the ["Rust signing key"](https://static.rust-lang.org/rust-key.gpg.ascii): +``` +pub rsa4096/0x85AB96E6FA1BE5FE 2013-09-26 [SC] + Key fingerprint = 108F 6620 5EAE B0AA A8DD 5E1C 85AB 96E6 FA1B E5FE +uid [ unknown] Rust Language (Tag and Release Signing Key) +sub rsa4096/0x8E9AA3F7AB3F5826 2013-09-26 [E] +sub rsa4096/0x5CB4A9347B3B09DC 2014-12-15 [S] +``` + +You can therefore pull the key from either the above or from a keyserver: +``` +$ gpg --keyserver hkps://keys.openpgp.org --receive 0x85AB96E6FA1BE5FE +``` +(Make sure to double check the whole key is the same, not just the fingerprint.) + +And then you can download the archive corresponding to your system and CPU architecture, verify the +signature and use the `cargo` binary from this archive to build Liana. Here is an example for +`amd64`: +``` +$ curl -O https://static.rust-lang.org/dist/rust-1.65.0-x86_64-unknown-linux-gnu.tar.gz +$ curl -O https://static.rust-lang.org/dist/rust-1.65.0-x86_64-unknown-linux-gnu.tar.gz.asc +$ gpg --verify rust-1.65.0-x86_64-unknown-linux-gnu.tar.gz.asc +$ tar -xzf rust-1.65.0-x86_64-unknown-linux-gnu.tar.gz +$ ./rust-1.65.0-x86_64-unknown-linux-gnu/cargo/bin/cargo build --release +``` + +### Through `rustup` + +[`rustup`](https://rust-lang.github.io/rustup/) is a software for installing the Rust toolchain. + +Some package managers distribute a version of `rustup`. Failing that, you can always follow the +"official" [installation method of `rustup`](https://www.rust-lang.org/tools/install) (that is, a +`curl`-`sh` pipe). + + +## Building the project + +Once you've got Cargo installed, building the project is a simple `cargo` invocation away: +``` +$ cargo build --release +``` +Make sure not to forget the `--release`, or you would build without optimizations otherwise. + +The `lianad` and `liana-cli` binaries will be in the `target/` directory at the root of the +repository: +``` +$ ls target/release/ +build deps examples incremental liana-cli liana-cli.d lianad lianad.d libliana.d libliana.rlib +``` + +To build the GUI, do the same but in the [`gui/`](../gui/) folder present at the root of the +repository: +``` +$ cd gui/ +$ cargo build --release +$ ls target/release/ +build deps examples incremental liana-gui liana-gui.d libliana_gui.d libliana_gui.rlib +``` diff --git a/doc/TRY.md b/doc/TRY.md new file mode 100644 index 00000000..54ec54c4 --- /dev/null +++ b/doc/TRY.md @@ -0,0 +1,125 @@ +## Quickly try out Liana + +*Just give me the TL;DR!* + +This document is a short set of instructions for trying out Liana on signet. It does not attempt to +give any nuance, details or describe alternative configurations. + +This guide mostly assumes you are running a 64-bit Linux. + +TODO: adapt the guide to Windows and MacOS. + + +### Step 0: dependencies + +We'll use basic tools such as: +- `curl` +- `tar` + +To run the simulator you will need: +- `git` (On Debian/Ubuntu `apt install gpg`) +- SDL2. See + [here](https://github.com/cryptoadvance/specter-diy/blob/6a6983e15e4d3c8c03937f8bee040de350ce722f/docs/build.md#prerequisities-simulator) + for the instructions depending on your system. (On Debian/Ubuntu `apt install libsdl2-dev`) + +To verify the downloads you will need: +- `shasum` +- `gpg` (On Debian/Ubuntu `apt install gpg`) + +To run the GUI you will need some libraries: +- `fontconfig` (On Debian/Ubuntu `apt install libfontconfig1-dev`) +- [`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config/) (On Debian/Ubuntu `apt install pkg-config`) +- [Libudev](https://www.freedesktop.org/software/systemd/man/libudev.html) (On Debian/Ubuntu `apt install libudev-dev`) + + +### Step 1: setup `bitcoind` + +Liana needs `bitcoind` to communicate with the Bitcoin network. Minimum supported version is 24.0. + +#### Download + +TODO: update to 24.0.1 when it's released. + +Download the `bitcoind` binary from [the official website of the Bitcoin Core +project](https://bitcoincore.org/bin/bitcoin-core-24.0/) according to your platform. + +Then verify the signature against a key you trust. The Bitcoin Core Github repo contains [a +list](https://github.com/bitcoin/bitcoin/blob/master/contrib/builder-keys/keys.txt) of frequent +signers. Mine is `590B7292695AFFA5B672CBB2E13FC145CD3F4304`. + +Finally, uncompress the archive to get access to the `bitcoind` binary. + +``` +curl -O https://bitcoincore.org/bin/bitcoin-core-24.0/bitcoin-24.0-x86_64-linux-gnu.tar.gz -O https://bitcoincore.org/bin/bitcoin-core-24.0/SHA256SUMS -O https://bitcoincore.org/bin/bitcoin-core-24.0/SHA256SUMS.asc +sha256sum --ignore-missing --check SHA256SUMS +gpg --keyserver hkps://keys.openpgp.org --receive 590B7292695AFFA5B672CBB2E13FC145CD3F4304 +gpg --verify SHASUMS.asc +tar -xzf bitcoin-24.0-x86_64-linux-gnu.tar.gz bitcoin-24.0/bin/bitcoind +``` + +For details on verifying your download, or for verifying the download on another platform please +refer to +[https://bitcoincore.org/en/download/#verify-your-download](https://bitcoincore.org/en/download/#verify-your-download). + +#### Start `bitcoind` on signet + +Run `bitcoind` in the background on the public signet network. If it is the first time you start a +signet Bitcoin on this machine it will take a few minutes to synchronize (depends on your connection +and hardware of course, but it shouldn't take longer than a handful of minutes). + +``` +./bitcoin-24.0/bin/bitcoind -signet -daemon +``` + + +### Step 2: setup a dummy signing device + +Liana does not support "hot keys" at the moment. It needs a connection to a signing device for +signing transactions. + +Let's start a Specter simulator. + +``` +git clone https://github.com/cryptoadvance/specter-diy +cd specter-diy +git checkout 6a6983e15e4d3c8c03937f8bee040de350ce722f +make simulate +``` + +A window will pop up. Choose a dummy pin code and generate a new key. Then go to settings, switch +network to signet. Then go to the next section. (Keep it running obviously, you'll need it.) + + +### Step 3: start Liana + +Get the latest Liana software release and start it. + +TODO: download and sig verification details + +Since you presumably never installed Liana, this will start the installer. Create a new wallet. + +Choose network Signet. For the primary key use the one from your dummy signing device, the Specter +simulator you just started. You can do that simply by clicking on "import". For the number of blocks +before the recovery key becomes active, you can choose anything valid. But prefer something small to +test the case where coins are soon to become accessible on the recovery branch. + +For the recovery key you could use another simulator but in this guide i'll just use a random xpub: +`tpubDDU2vzv4Rk2kU8VjDDQBWYTb7tmSd9ddV4ERmm5VesfoaxBJQm3CyNc4fjcYAzEqXn3YQ8dxpzkhQjpxT3Nqp7yQh1UMczL1MMfTSKXNv3n/<0;1>/*`. +You can generate one from, for instance https://iancoleman.io/bip39/. But make sure to append +`/<0;1>/*` to it, this is to be able to derive both change and receive addresses from the same +descriptor. + +Make the next step happy by ticking the "i backed up my descriptor" checkbox. + +Import the descriptor to your Specter by clicking on the `specter-simulator` tile. + +Finally, configure the connection to `bitcoind`. The default should work for what we did in this +guide. Click sur continue and finalize the installation. + + +### Step 4: have fun + +You can generate a receive address in the "Receive" menu. You can get signet coins from the signet +faucet at https://signet.bc-2.jp/. + +Keep in mind that signet coins have no value!