Learning-Bitcoin-from-the-Command-Line/16_1_Setting_Up_Libwally.md

# 16.1: Setting Up Libwally

> **NOTE:** This is a draft in progress, so that I can get some feedback from early reviewers. It is not yet ready for learning.

This first section will explain how to download Libwally and how to get it working.

> :book: ***What is Libwally?*** Libwally is a library of primitives helpful for the creation of wallets that is cross-platform and cross-language, so that the same functions can be used everywhere. There are [extensive docs](https://wally.readthedocs.io/en/release_0.7.8/). It's made available as part of Blockstream's [Elements Project](https://github.com/ElementsProject).

## Installing Libwally

As usual, you'll need some packages on your system:
```
$ sudo apt-get install git
$ sudo apt-get install dh-autoreconf
```

You can download Libwally from its Git repo:
```
$ git clone https://github.com/ElementsProject/libwally-core
```
You can then get things installed:
```
$ ./tools/autogen.sh
```
As with `libbitcoinrpc`, you may wish to install this in `/usr/include` and `/usr/lib` for ease of usage. Just modify the appropriate line in the `configure` program:
```
< ac_default_prefix=/usr
---
> ac_default_prefix=/usr/local
```
Afterward you can finish your prep:
```
$ ./configure
$ make
```
You can then verify that tests are work:
```
$ make check
Making check in src
make[1]: Entering directory '/home/standup/libwally-core/src'
Making check in secp256k1
make[2]: Entering directory '/home/standup/libwally-core/src/secp256k1'
make  check-TESTS
make[3]: Entering directory '/home/standup/libwally-core/src/secp256k1'
make[4]: Entering directory '/home/standup/libwally-core/src/secp256k1'
============================================================================
Testsuite summary for libsecp256k1 0.1
============================================================================
# TOTAL: 0
# PASS:  0
# SKIP:  0
# XFAIL: 0
# FAIL:  0
# XPASS: 0
# ERROR: 0
============================================================================
make[4]: Leaving directory '/home/standup/libwally-core/src/secp256k1'
make[3]: Leaving directory '/home/standup/libwally-core/src/secp256k1'
make[2]: Leaving directory '/home/standup/libwally-core/src/secp256k1'
make[2]: Entering directory '/home/standup/libwally-core/src'
make  check-TESTS check-local
make[3]: Entering directory '/home/standup/libwally-core/src'
make[4]: Entering directory '/home/standup/libwally-core/src'
PASS: test_bech32
PASS: test_psbt
PASS: test_psbt_limits
PASS: test_tx
============================================================================
Testsuite summary for libwallycore 0.7.8
============================================================================
# TOTAL: 4
# PASS:  4
# SKIP:  0
# XFAIL: 0
# FAIL:  0
# XPASS: 0
# ERROR: 0
============================================================================
make[4]: Leaving directory '/home/standup/libwally-core/src'
make[3]: Nothing to be done for 'check-local'.
make[3]: Leaving directory '/home/standup/libwally-core/src'
make[2]: Leaving directory '/home/standup/libwally-core/src'
make[1]: Leaving directory '/home/standup/libwally-core/src'
make[1]: Entering directory '/home/standup/libwally-core'
make[1]: Nothing to be done for 'check-am'.
make[1]: Leaving directory '/home/standup/libwally-core'
```
Finally, you can install:
```
$ sudo make install
```

## Preparing for Libwally

As usual, you'll need to include appropriate files and link appropriate libraries to use Libwally.

### Including the Files

There are a considerable number of possible include files:

```
$ ls /usr/include/wally*
/usr/include/wally_address.h  /usr/include/wally_bip39.h   /usr/include/wally_elements.h  /usr/include/wally_script.h
/usr/include/wally_bip32.h    /usr/include/wally_core.h    /usr/include/wally.hpp	  /usr/include/wally_symmetric.h
/usr/include/wally_bip38.h    /usr/include/wally_crypto.h  /usr/include/wally_psbt.h	  /usr/include/wally_transaction.h
```
Fortunately, the file names largely match the sections in the [docs](https://wally.readthedocs.io/en/release_0.7.8/), so you should be able to include the correct files based on what you're doing.

### Including the Libraries

You also will need to link appropriate libraries:
```
$ ls /usr/lib/libsecp* /usr/lib/libwally*
/usr/lib/libsecp256k1.a   /usr/lib/libwallycore.la  /usr/lib/libwallycore.so.0
/usr/lib/libsecp256k1.la  /usr/lib/libwallycore.so  /usr/lib/libwallycore.so.0.0.0
```
Mostly, we'll be using `libwallycore`.

## Setting Up a Libwally Program

Compared to some of the previous libraries, Libwally is ridiculously easy to initialize:
```
lw_response = wally_init(0);
```
And then when you're done, there's a handy function to clean up any allocated memory:
```
wally_cleanup(0);
```
In both cases, the argument is for flags, but is currently set to `0`.

### Testing a Test Libwally Program

The src directory contains [testwally.c](/src/16_1_testwally.c), which just shows how the initialize and cleanup work.

You can compile it as follows:
```
$ cc testwally.c -lwallycore -o testwally
```
Afterward you can run it:
```
$ ./testwally
Startup: 0
```
The "Startup" value is the return from `wally_init`. The `0` value may look discouraging, but that's what you want to see:
```
include/wally_core.h:#define WALLY_OK      0 /** Success */
```

## Summary: Setting Up Libwally

By installing the Libwally includes and libraries, you can use it to access a number of cryptographic and library functions, which can complement your RPC and ZMG libraries.

So what does it do exactly? That's what the next sections detail.

## What's Next?

Learn more about "Programming Bitcoin with Libwally" in [16.2: Using BIP32 in Libwally](16_2_Using_BIP32_in_Libwally.md).