Merge #128: More documentation
2cfcae286c760791011c03c7d9a58fec99fb0595 doc: add a guide for quickly trying out Liana (Antoine Poinsot)
973405c6798d0cf7aacaae7ab1d453395c2c2972 README: tiny cleanup to the installing section (Antoine Poinsot)
9b29c2e0aa65ef1301334466690e15b4d12ce506 doc: document how to build the project from source (Antoine Poinsot)
Pull request description:
This adds instructions for building from source, as well as a guide to quickly try out the software on Signet.
ACKs for top commit:
darosior:
ACK 2cfcae286c760791011c03c7d9a58fec99fb0595 -- it's only doc, we can iterate later on.
Tree-SHA512: 5e2a2af4905bf17c6e3c05957c551ee7ccfb527c231c84ee26a5f74010c674530a36c995ef54ccd1a225c661d3bebedd68e253cd9c48bc810687d3ff28ce5e5c
This commit is contained in:
Antoine Poinsot
commit
40eb605aea
@ -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
|
||||
|
||||
|
||||
89
doc/BUILD.md
Normal file
89
doc/BUILD.md
Normal file
@ -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) <rust-key@rust-lang.org>
|
||||
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
|
||||
```
|
||||
125
doc/TRY.md
Normal file
125
doc/TRY.md
Normal file
@ -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!
|
||||
Loading…
x
Reference in New Issue
Block a user