Category: The Libbitcoin Tutorials

Libbitcoin enables developers to make high level calls to the bitcoin p2p network, allowing them to work with data queried from the blockchain.

In order to call blockchain data, a libbitcoin-server needs to be queried using libbitcoin’s networking API which is exposed in the libbitcoin-client library. Click here to learn how to install libbitcoin-client.

There are two core parts to making a call to a libbitcoin-server. First, an obelisk client object is instantiated to set the parameters of the connection we want to make to a server. Second, libbitcoin is an asynchronous toolkit which avoids blocking other functions when using a worker or making an api call. Therefore, the use of callback function handlers is necessary when making a query.

So, firstly I’ve created a file called helloBlockchain.cpp and included the necessary libraries as well as namespace.

#include <bitcoin/bitcoin.hpp>
#include <bitcoin/client.hpp>
#include <string.h>
#include <iostream>
#include <cstdint>

using namespace bc;

Next, inside the main function, a connection_type object can be used to set all the parameters of the connection. Including variables such as: retry attempts, timeout time and the server endpoint.

int main()
{
 client::connection_type connection = {};
 connection.retries = 3;
 connection.timeout_seconds = 8;
 connection.server = config::endpoint("tcp://mainnet.libbitcoin.net:9091");
}

Now, also in the main function, we are going to need to create the call back functions. We’ll need one for the completion of the call and one if the call returns an error. For both, we are going to simply print out the returned error code or block height.

 const auto on_reply = [](size_t blockHeight) 
 {
 std::cout << "Height: " &amp;lt;&amp;lt; blockHeight << std::endl;

 };

 static const auto on_error = [](const code& ec) 
 {

 std::cout << "Error Code: " << ec.message() << std::endl;

 };

Finally, now that everything is set up we can connect to the network and query the current block height of the network. We just need to pass our connection struct to a obelisk_client object and then use its connect function to establish a connection with the server. Note, that by nesting this call in an if-statement we create a nice little error catching message printed to the console.

 client::obelisk_client client(connection);

 if(!client.connect(connection))
 {
 std::cout << "Fail" << std::endl;
 } else {
 std::cout << "Connection Succeeded" << std::endl;
 }

Once the connection is established, we can simply use the client’s fetch height function and then immediately use its wait function to keep the app running while the asynchronous functions resolve. Like so:

 client.blockchain_fetch_last_height(on_error, on_reply);
 client.wait();

}

With that, this program can be compiled and run similarly to the other programs with the exception that libbitcoin-client must be passed as a lib to the command line compiler.

alpha$ g++ -std=c++11 -o height helloBlockchain.cpp $(pkg-config --cflags libbitcoin --libs libbitcoin libbitcoin-client)
alpha$ ./height

The output should look similar to this, displaying the current block height or an error code, and whether or not the connection succeeded.

Note, that this can be used to call the testnet by simply passing the libbitcoin server “tcp://testnet.libbitcoin.net:9091” to the connection struct.

As always, full sample code can be found on github under the networking directory.

In order to work with blockchain data with libbitcoin, it is necessary to install and build the Libbitcoin-Client library which exposes api calls to Libbitcoin-Servers thus enabling developers to work with data queried from the p2p network.

Installing Libbitcoin-Client is very similar to installing the core libbitcoin library, it simply requires installing one other dependency, another libbitcoin library called Libbitcoin-Protocol. Libbitcoin-Protocol is a custom query protocol for getting blockchain data from a Libbitcoin-Server, it is built on zeroMQ and provides a clean way of communicating with blockchain servers. Libbitcoin-Protocol is also a clean frontier for innovation within the libbitcoin ecosystem, enabling open source programmers to create custom query functions that increase privacy and/or security.

To install simply invoke the following commands in your working directory, similarly to how libbitcoin was installed.

alpha$ git clone https://github.com/libbitcoin/libbitcoin-protocol.git
alpha$ cd libbitcoin-protocol
alpha$ git branch --all
alpha$ git checkout remotes/origin/version3
alpha$ git checkout -b version3
alpha$ ./autogen.sh
alpha$ ./configure
alpha$ make 
alpha$ sudo make install

Once the Libbitcoin-Protocol is installed building and installing Libbitcoin-Client is, again, very similar:

alpha$ git clone https://github.com/libbitcoin/libbitcoin-client.git
alpha$ cd libbitcoin-client
alpha$ git branch --all
alpha$ git checkout remotes/origin/version3
alpha$ git checkout -b version3
alpha$ ./autogen.sh
alpha$ ./configure
alpha$ make 
alpha$ sudo make install

Once this build is completed, Libbitcoin-Client should be installed allowing the developer to create applications that use blockchain data by querying Libbitcoin-Servers in an asynchronous fashion.

Libbitcoin offers several options for installation.

Firstly, If you would like to simply use libbitcoin’s bitcoin functionality without having to write any code you can download the signed executable binaries for some of the libbitcoin applications. These binaries require no installation and are programs simply meant to be run on your machine. Binaries exist for the libbitcoin-node, libbitcoin-server, and libbitcoin-explorer applications. The most useful, for beginners, is the libbitcoin-explorer command line utility which allows you to explore the full range of bitcoin functions from the command line. This application exposes useful commands for hashing, key generation, transaction creation and submission as well as blockchain querying for balances, height and utxo’s.

Next, Libbitcoin offers a build system in the repository libbitcoin-build. This automated build system installs the entire toolchain from a single script. This option is great for windows or linux users familiar with GSL, travis or automated build systems in general.

Finally, each individual repository can be built with autotools on linux and OSX or with an install script on most platforms. Building libraries individually is useful if you only want to use a specific module of libbitcoin without installing the entire toolchain, though all modules depend on the foundational libbitcoin library.

I will demonstrate installation and building from source of the main libbitcoin library on Mac OSX. This process can be replicated with all other libraries, simply ensure you have installed its specific dependencies before repeating this process. This method is also beneficial if you would like to stay on the bleeding edge of libbitcoin development as it allows you to install the library from a github branch other than the stable realease branch (v3.0).

First, navigate to your working directory and once inside of it, proceed to cloning the libbitcoin repository.

alpha$ git clone https://github.com/libbitcoin/libbitcoin.git

Once the repo is cloned we’re first going to want to switch branches so that we can install the version 3 code. If you would like to install the bleeding edge(and likely, unstable) version of libbitcoin simply build the library using the master branch. First, we’ll need to switch into the local libbitcoin repository with:

alpha$ cd libbitcoin
alpha$ git branch --all

This command will display all available remote working branches, to build version 3 we’ll need to check it out first, using the following commands. The second command here creates a local clone of the branch to be worked on:

alpha$ git checkout remotes/origin/version3
alpha$ git checkout -b version3

Now that we have the stable v3 source code, we can install the dependencies. On Mac OSX use:

alpha$ clang++ --version

to make sure your system has LLVM > 6.0. Additionally, OSX users will need to have the Xcode developer tools installed, which can be achieved by invoking:

alpha$ xcode-select --install

Now, in order to install libbitcoin’s other dependencies, brew will need to be used. If you don’t have Homebrew, install it with:

alpha$ ruby "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Most of the packages libbitcoin relies on can be installed with brew using a single command.

alpha$ brew install autoconf automake libtool pkgconfig wget

Next, a small wrinkle, boost version 1.57 or greater needs to be installed and the current version of boost is 1.63.0. Now, in my personal experience libbitcoin failed to build or compile on OSX, throwing many errors at boost, using the latest version. I’m unaware as to whether or not this bug is on my machine, OSX, or libbitcoin v3 in general; but in order to build libbitcoin I needed to install boost 1.59. This can be achieved in a way very similar to how the latest version of boost is installed, simply append @[1.59] to the brew command.

//alpha$ brew install boost 
alpha$ brew install boost@1.59

Now all of libbitcoin’s dependencies are installed and we are ready to build the library. Now we just need to use autotools to generate the build artifacts and configuration settings.

alpha$ ./autogen.sh
alpha$ ./configure

Once those processes are done, make is used to build the library.

alpha$ make
alpha$ sudo make install

Boom! Once complete, libbitcoin v3 should be installed on your system. You can test it out by compiling your first libbitcoin program following this tutorial.

For more libbitcoin tutorials visit aaronjaramillo.org || For more libbitcoin sample code visit Github

Libbitcoin is a modular framework making it extremely adaptable to the needs of the developer. The libbitcoin maintainers go to great lengths to design a system that avoids hardcoding values and parameters into the framework. The wallet namespace classes that deal with various key types do not have hardcoded prefix and version values, allowing the developer(us) to easily use these classes for currencies other than bitcoin.

By simply passing the necessary version values to the constructor functions we can generate keys for various altcoins. First, I’ve defined a function to generate a WIF private key and a payment address, displaying both to the user. This function takes the version prefix argument as a short.

The libbitcoin ec_private constructor takes a 2 byte version argument with most significant byte being the WIF version code and the least significant byte being the address prefix. So we simply instantiate the ec_private object with the altcoins specific prefix and some entropy. We can now use these altcoin keys with libbitcoin functions as we normally would.(working with keys in libbitcoin).

void showKeys(short altcoin)
{
 data_chunk seedChunk(16);
 pseudo_random_fill(seedChunk);

 ec_secret secret = sha256_hash(seedChunk);

 wallet::ec_private privateKey(secret, altcoin);
 std::cout << "\nWIF: " << privateKey.encoded() << std::endl;
 std::cout << "Payment Address: " << privateKey.to_payment_address().encoded() << std::endl; 
}

Now that we have a function that generates altcoin keys, I’ve declared three variables as the version codes for three Altcoins. Note that these value are the hexadecimal WIF code followed by the hexadecimal address prefix. So for Litecoin, the WIF code if 0xB0 and the version prefix is 0x30 which should result in an address that begins with “L”. Simply call the key generator function and pass the altcoin value to the function.

int main()
{
 short LTC = 0xB030; //L 0xB0, 0x30
 short DOGE = 0x9E1E; //D 0x9E, 0x1E
 short DASH = 0xCC4C; //X 0xCC, 0x4C

 showKeys(LTC);
 showKeys(DOGE);
 showKeys(DASH);

}

This script can be compiled as usual, with libbitcoins library flags.

 $ g++ -std=c++11 -o altcoin AltcoinKeys.cpp $(pkg-config --cflags libbitcoin --libs libbitcoin)
$ ./altcoin

The output should look like this. Be sure to check the first letter matches the prefix for the altcoin.

As usual the full code for these blog post can be found on github. To learn more about using libbitcoin with altcoins check here.

OP_RETURN

OP_RETURN is the formal way of embedding data into the blockchain. By using a special script operation, we can create an output with a value of 0 and a script that includes up to 80 bytes of arbitrary data. By using the OP_RETURN code we create an unspendable output, meaning no unlocking script will satisfy this and the network nodes can remove them from their utxo mempools. Now, these transaction’s still need to pay a fee in order for the miner’s to include them in a block, and since the size of these transactions is generally higher than a standard transaction the fee included should be higher to ensure it gets confirmed. Any data can be stored in this field of the output, including special protocol tags for digital assets, contracts and metacoins.

rawTX

In libbitcoin, creating a null data script is easy with the help of a stack factory which means we just need to create another output with a special script to add data. I’m going to append my previous rawTX program to include another output which includes some data.

For the initial output I’m going to send the value of a utxo back to myself, minus the miner fee. I’m going to do this by updating the presets in my getInput() testing function. I also went ahead and added a 7th preset field with a string of ascii characters to post on the blockchain.

//This is a testing class
//use it to pass hardcoded strings
//to the prompts by changing the string
//declarations function and passing the preset
std::string getInput(int preset)
{
 if(preset == 1)
 {
 
 return "[ YOUR MNEMONIC SEED ]"; //Mnemonic
 } else if (preset == 2)
 {
 return "1"; //Index of child key
 }else if (preset == 3)
 {

 return "n2ge1S4bLDvJKx8AGXrK5JHY2D5cReVytu"; //Destination Adress
 }else if (preset == 4)
 {
 return "1.48192700"; //Amount of Bitcoin to Spend
 } else if (preset == 5)
 {
 return "ce7f741625dfa86a50a1f18e3664e927441e27ef2f1c526e3aff8ea6c7a650fd"; //UTXO hash to spend

 }else if (preset == 6)
 {
 return "0"; //Output index of UTXO
 }else if (preset == 7) 
 {
 return "HelloWorld";
 }
}

Now, all I need to do to include the data in the transaction is add get the string and use a special made libbitcoin serializer to write the string as data. Bitcoin output’s can have up to 80 bytes of data included so we are making the data chunk 80 bytes.

For obvious reasons, namely fees, it’s usually practical to only use the amount of data you need as not to bloat the blockchain when not on the testnet.

Once we have the data_chunk and an 80 byte buffer we can create the serializer and deserializer and write the string to the data chunk. After that we can output the encoded bytes to the terminal and save the bytes in the nullData variable.

 std::string messageString = getInput(7);
 data_chunk data(80);
 auto source = make_safe_deserializer(data.begin(), data.end());
 auto sink = make_unsafe_serializer(data.begin());
 sink.write_string(messageString);

 const auto nullData = source.read_bytes(80);
 std::cout <<; "Message: " << std::endl;
 std::cout << encode_base16(nullData) << std::endl; 

Once the data is saved, we can create an output object and use a to_null_data_pattern script factory to pass the data into an OP_RETURN script. By passing that script factory and and the value 0 to the output setters, the output is finished.

 output output2 = output();
 output2.set_script(script(script().to_null_data_pattern(nullData)));
 output2.set_value(0);

With the output done, it simply needs to be pushed back on the transaction objects outputs vector.

 //build TX
 transaction tx = transaction();
 tx.inputs().push_back(input1);
 tx.outputs().push_back(output1);
 tx.outputs().push_back(output2);

This script can be compile the same as the last rawTX program and the displayed rawTX can be broadcast to the network embedding the message.

 $ g++ -std=c++11 -o rawTX rawTX.cpp $(pkg-config --cflags libbitcoin --libs libbitcoin)
$ ./rawTX

The output should look like this:

Inspect your transaction on blocktrail and you can see the two script’s one sending the change back to you and the other with your encoded message.

This hex data represents the ascii characters in your message, some block explorers, like blocktrail will convert the hex to ascii for you:

Bam! Data Embedded for all Eternity.