ℹ️ NOTE: This section has been recently added to the course and is an early draft that may still be awaiting review. Caveat reader.
This first section will explain how to download the Libwally C Library and get it working.
📖 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 online docs. Libwally is made available as part of Blockstream's Elements Project.
As usual, you'll need some packages on your system:
$ sudo apt-get install git
$ sudo apt-get install dh-autoreconf
You can then download Libwally from its Git repo:
$ git clone https://github.com/ElementsProject/libwally-core
Afterward, you can begin the configuration process:
$ ./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 working:
$ 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
So how do you use Libwally in a program? As usual, you'll need to include appropriate files and link appropriate libraries for your code.
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, so you should be able to include the correct files based on what you're doing, after including the ubiquitous wally_core.h.
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, you'll be using libwallycore.
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.
The src directory contains testwally.c, which just shows how the initialize and cleanup functions 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 initially appear discouraging, but it's's what you want to see:
include/wally_core.h:#define WALLY_OK 0 /** Success */
You should also install Libsodium to get access to a high quality random number generator for testing purposes.
⚠️ WARNING: The generation of random numbers can be one of the greatest points of vulnerability in any Bitcoin software. If you do it wrong, you expose your users to attacks because they end up with insecure Bitcoin keys, and this isn't a theoretical problem. BlockchainInfo once incorrectly generated 0.0002% of their keys, which resulted in the temporary loss of 250 Bitcoins. Bottom line: make sure you're totally comfortable with your random number generation. It might be Libsodium, or it might be an even more robust TRNG method.
You can download a Libsodium tarball and then follow the instructions at Libsodium installation to install.
First, untar:
$ tar xzfv /tmp/libsodium-1.0.18-stable.tar.gz
Then, adjust the configure file exactly as you have the other libraries to date:
< ac_default_prefix=/usr
---
> ac_default_prefix=/usr/local
Finally, make, check, and install:
$ make
$ make check
...
============================================================================
Testsuite summary for libsodium 1.0.18
============================================================================
# TOTAL: 77
# PASS: 77
# SKIP: 0
# XFAIL: 0
# FAIL: 0
# XPASS: 0
# ERROR: 0
============================================================================
...
$ sudo make install
This course will only use libsodium for one small (but crucial!) bit of entropy generation, but watch for it in the next section.
By installing the Libwally (and Libsodium) includes and libraries, you gain access to a number of cryptographic and wallet functions, which can complement your RPC and ZMQ libraries (or your command-line bitcoin-cli).
So what precisely can you do now? That's what the rest of this chapter is about.
Learn more about "Programming Bitcoin with Libwally" in 17.2: Using BIP39 in Libwally.