1# libwally-core 2 3Wally is a cross-platform, cross-language collection of useful primitives 4for cryptocurrency wallets. 5 6Read the API documentation at https://wally.readthedocs.io. 7 8Note that library interfaces may change slightly while the library design matures. Please see the [CHANGES](./CHANGES.md) file to determine if the API has changed when upgrading. 9 10Please report bugs and submit patches to [Our github repository](https://github.com/ElementsProject/libwally-core). If you wish to report a security issue, please read [Our security reporting guidelines](./SECURITY.md). 11 12[![Build Status](https://travis-ci.org/ElementsProject/libwally-core.svg?branch=master)](https://travis-ci.org/ElementsProject/libwally-core) 13[![Documentation Status](https://readthedocs.org/projects/wally/badge/?version=latest)](https://wally.readthedocs.io/en/latest/?badge=latest) 14 15## Platforms 16 17Wally can currently be built for: 18- Linux 19- Android 20- macOS 21- iOS 22- Windows 23- WebAssembly 24 25And can be used from: 26- C and compatible languages which can call C interfaces 27- C++ (see include/wally.hpp for C++ container support) 28- Python 2.7+ or 3.x 29- Java 30- Javascript via node.js or Cordova or WebAssembly/Emscripten compatible 31 32## Building 33 34``` 35# Initialise the libsecp sources (Needs to be run only once) 36$ git submodule init 37$ git submodule sync --recursive 38$ git submodule update --init --recursive` 39 40# Build 41$ ./tools/autogen.sh 42$ ./configure <options - see below> 43$ make 44$ make check 45``` 46 47### Building on macOS 48 49Using homebrew, 50``` 51$ brew install gnu-sed 52``` 53 54If you wish to enable the SWIG interface, you 55will need install the Java JDK 8 or newer, and install SWIG: 56 57``` 58$ brew install swig 59``` 60 61### configure options 62 63- `--enable-debug`. Enables debugging information and disables compiler 64 optimisations (default: no). 65- `--enable-export-all`. Export all functions from the wally shared library. 66 Ordinarily only API functions are exported. (default: no). Enable this 67 if you want to test the internal functions of the library or are planning 68 to submit patches. 69- `--enable-swig-python`. Enable the [SWIG](http://www.swig.org/) Python 70 interface. The resulting shared library can be imported from Python using 71 the generated interface file `src/swig_python/wallycore/__init__.py`. (default: no). 72- `--enable-python-manylinux`. Enable [manylinux](https://github.com/pypa/manylinux) 73 support for building [PyPI](https://pypi.org/) compatible python wheels. Using 74 the resulting library in non-python programs requires linking with `libpython.so`. 75- `--enable-swig-java`. Enable the [SWIG](http://www.swig.org/) Java (JNI) 76 interface. After building, see `src/swig_java/src/com/blockstream/libwally/Wally.java` 77 for the Java interface definition (default: no). 78- `--enable-elements`. Enables support for [Elements](https://elementsproject.org/) 79 features, including [Liquid](https://blockstream.com/liquid/) support. 80- `--enable-js-wrappers`. Enable the Node.js and Cordova Javascript wrappers. 81 This currently requires python to be available at build time (default: no). 82- `--enable-coverage`. Enables code coverage (default: no) Note that you will 83 need [lcov](http://ltp.sourceforge.net/coverage/lcov.php) installed to 84 build with this option enabled and generate coverage reports. 85- `--disable-shared`. Disables building a shared library and builds a static 86 library instead. 87- `--disable-tests`. Disables building library tests. 88- `--disable-clear-tests`. Disables just the test_clear test (required to pass 89 the test suite with some compilers). 90 91### Recommended development configure options 92 93``` 94$ ./configure --enable-debug --enable-export-all --enable-swig-python --enable-swig-java --enable-coverage 95``` 96 97### Compiler options 98 99Set `CC=clang` to use clang for building instead of gcc, when both are 100installed. 101 102### Python 103 104For non-development use, you can install wally with `pip` as follows: 105 106``` 107pip install wallycore==0.8.3 108``` 109 110For python development, you can build and install wally using: 111 112``` 113$ pip install . 114``` 115 116It is suggested you only install this way into a virtualenv while the library 117is under heavy development. 118 119If you wish to explicitly choose the python version to use, set the 120`PYTHON_VERSION` environment variable (to e.g. `2.7`, `3`, `3.7` etc) before 121running `pip` or (when compiling manually) `./configure`. 122 123You can also install the binary [wally releases](https://github.com/ElementsProject/libwally-core/releases) 124using the released wheel files without having to compile the library, e.g.: 125 126``` 127pip install wallycore-0.8.3-cp37-cp37m-linux_x86_64.whl 128``` 129 130The script `tools/build_python_manylinux_wheels.sh` builds the Linux release files 131and can be used as an example for your own python projects. 132 133### Android 134 135Android builds are currently supported for all Android binary targets using 136the Android NDK. The script `tools/android_helpers.sh` can be sourced from 137the shell or scripts to make it easier to produce builds: 138 139``` 140$ export ANDROID_HOME=/opt/android-sdk 141$ . ./tools/android_helpers.sh 142 143$ android_get_arch_list 144armeabi-v7a arm64-v8a x86 x86_64 145 146# Prepare to build 147$ ./tools/cleanup.sh 148$ ./tools/autogen.sh 149 150# See the comments in tools/android_helpers.sh for arguments 151$ android_build_wally armeabi-v7a $ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64 19 "--enable-swig-java" 152``` 153 154The script `tools/build_android_libraries.sh` builds the Android release files and 155can be used as an example for your own Android projects. 156 157### WebAssembly 158 159WebAssembly is available as a preview feature. Users may want to avoid using wally compiled for 160wasm for signing or encryption/decryption as the transpiled code may not remain constant time. 161 162Building wally as wasm requires following emsdk instructions for 163your [platform](https://webassembly.org/getting-started/developers-guide/) and sourcing 164the `emsdk_env.sh` file: 165 166``` 167# Set up the environment variables for the toolchain 168$ source $HOME/emsdk/emsdk_env.sh 169 170# Optionally set the list of wally functions to export to wasm (default: all) 171$ export EXPORTED_FUNCTIONS="['_malloc','_free','_wally_init','_wally_cleanup',...]" 172 173`# Build 174$ ./tools/build_wasm.sh [--enable-elements] 175``` 176 177The script `tools/build_wasm.sh` builds the `wallycore.html` example as well 178as the required `wallycore.js` and `wallycore.wasm` files, which can be used 179as an example for your own WebAssembly projects. 180 181Open `wallycore.html` in a browser via a webserver like [nginx](https://www.nginx.com/) 182or `python2 -m SimpleHTTPServer 8000` to run the example. 183 184## Cleaning 185 186``` 187$ ./tools/cleanup.sh 188``` 189 190## Submitting patches 191 192Please use pull requests on [github](https://github.com/ElementsProject/libwally-core) to 193submit. Before producing your patch you should format your changes 194using [uncrustify](https://github.com/uncrustify/uncrustify.git) version 0.60 or 195later. The script `./tools/uncrustify` will reformat all C sources in the library 196as needed, with the currently chosen uncrustify options. 197 198To reformat a single source file, use e.g.: 199``` 200$ ./tools/uncrustify src/transaction.c 201``` 202 203Or to reformat all source files, pass no arguments: 204``` 205$ ./tools/uncrustify 206``` 207 208If you have added new API functions in your patch, run `./tools/build_wrappers.py` 209to update the auto-generated support code for various platforms. 210 211You should also make sure the existing tests pass and if possible write tests 212covering any new functionality, following the existing style. You can run the 213tests via: 214``` 215$ make check 216``` 217 218Python ctypes tests (in `./src/test/`) are strongly preferred, but you can add 219to the other test suites if your changes target a specific language or your 220tests need to be written at a higher level of abstraction. 221 222## Generating a coverage report 223 224To generate an HTML coverage report, install `lcov` and use: 225 226``` 227$ ./tools/cleanup.sh 228$ ./tools/autogen.sh 229$ ./configure --enable-debug --enable-export-all --enable-swig-python --enable-swig-java --enable-js_wrappers --enable-coverage --enable-elements 230$ make 231$ ./tools/coverage.sh clean 232$ make check 233$ ./tools/coverage.sh 234``` 235 236The coverage report can then be viewed at `./src/lcov/src/index.html`. Patches 237to increase the test coverage are welcome. 238 239## Users of libwally-core 240 241Projects and products that are known to depend on or use `libwally`: 242* [Blockstream Green Command Line Wallet](https://github.com/Blockstream/green_cli) 243* [Blockstream Green Development Kit](https://github.com/Blockstream/gdk) 244* [Blockstream Green Wallet for Android](https://github.com/Blockstream/green_android) 245* [Blockstream Green Wallet for iOS](https://github.com/Blockstream/green_ios) 246* [Blockstream Green Wallet for Desktops](https://github.com/Blockstream/green_qt) 247* [Blockstream Jade Hardware Wallet](https://github.com/Blockstream/Jade) 248* [BitBox02 Hardware Wallet](https://github.com/digitalbitbox/bitbox02-firmware) 249* [Blockstream Blind PIN Server](https://github.com/Blockstream/blind_pin_server) 250* [Blockstream/liquid-melt](https://github.com/Blockstream/liquid-melt) 251* [Blockstream/liquid_multisig_issuance](https://github.com/Blockstream/liquid_multisig_issuance) 252* [c-lightning](https://github.com/ElementsProject/lightning) 253* [gdk_rpc for bitcoind/liquidd](https://github.com/Blockstream/gdk_rpc) 254* [GreenAddress Recovery Tool](https://github.com/greenaddress/garecovery) 255* [GreenAddress Wallet for Windows/Mac/Linux](https://github.com/greenaddress/WalletElectron) 256* [GreenAddress Web Files](https://github.com/greenaddress/GreenAddressWebFiles) 257* [LibWally Swift](https://github.com/blockchain/libwally-swift) 258* [Multy-Core](https://github.com/Multy-io/Multy-Core) 259 260Please note that some of the listed projects may be experimental or superseded. 261