Libbitcoin Client

The libbitcoin-client library provides an abstraction over the low level networking calls required to communicate with Bitcoin Server (bs) or other services implementing the Libbitcoin client-server protocol. With few exceptions (fetch-stealth and watch-address), the client is compatible with both Obelisk and Bitcoin Server.

Example (Version3)

#include <cstddef>
#include <iostream>
#include <bitcoin/client.hpp>

int main(int argc, char* argv[])
{
    if (argc < 2)
    {
        std::cerr << "server address required" << std::endl;
        return 1;
    }

    // 3 second timeout, 0 retries
    bc::client::obelisk_client client(3, 0);

    if (!client.connect({ argv[1] }))
    {
        std::cerr << "connect failed: " << argv[1] << std::endl;
        return 1;
    }

    const auto on_error = [](const bc::code& ec)
    {
        std::cerr << "fetch failed: " << ec.message() << std::endl;
    };
 
    const auto on_done = [](size_t height)
    {
        std::cout << "height: " << height << std::endl;
    };

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

    return 0;
}

Example (Version2)

#include <cstddef>
#include <iostream>
#include <czmq++/czmqpp.hpp>
#include <bitcoin/client.hpp>

int main(int argc, char* argv[])
{
    czmqpp::context context;
    czmqpp::socket socket(context, ZMQ_DEALER);
 
    if (argc < 2 || socket.connect(argv[1]) < 0)
    {
        std::cerr << "server address required" << std::endl;
        return 1;
    }
 
    auto stream = std::make_shared<bc::client::socket_stream>(socket);
    auto message = std::static_pointer_cast<bc::client::message_stream>(stream);
    auto obelisk = std::make_shared<bc::client::obelisk_codec>(message);
 
    const auto error_handler = [](const std::error_code& ec)
    {
        std::cerr << "error: " << ec.message() << std::endl;
    };
 
    const auto handler = [](size_t height)
    {
        std::cout << "height: " << height << std::endl;
    };
 
    obelisk->fetch_last_height(error_handler, handler);
 
    while (obelisk->outstanding_call_count())
    {
        czmqpp::poller poller;
        poller.add(socket);
 
        const auto delay = static_cast<int>(obelisk->wakeup().count());
        if (!delay)
            break;
 
        poller.wait(delay);
        if (poller.terminated())
            break;
 
        if (!poller.expired())
            stream->signal_response(obelisk);
    }
 
    return 0;
}

Messaging

The client-server protocol (API) is build on ØMQ (aka ZMQ, ZeroMQ and Zero Message Queue), a "High-speed asynchronous I/O engine, in a tiny library." ØMQ sits directly on sockets and, "Carries messages across inproc, IPC, TCP, TIPC, multicast." The API supports the pub-sub pattern (e.g. monitoring Bitcoin addresses) and the router-dealer pattern (e.g. requesting stealth transactions).

Authentication and Encryption

The API incorporates CurveZMQ, "An authentication and encryption protocol for ZeroMQ." CurveZMQ is based on CurveCP and NaCl, providing fast, secure elliptic-curve crypto.

Private key certificates are self-generated as ZPL (ZeroMQ Property Language) encoded files with public and secret key properties. The keys are Z85 - (ZeroMQ Base-85 Encoding Algorithm) encoded elliptic curve points. Keys can be fabricated by Bitcoin Explorer (bx) as follows (version 2).

$ bx cert-new citizen4.private

$ cat citizen4.private
#   ****  Generated on 2015-05-18 15:09:59 by CZMQ  ****
#   ZeroMQ CURVE **Secret** Certificate
#   DO NOT PROVIDE THIS FILE TO OTHER USERS nor change its permissions.

metadata
curve
    public-key = "Mu^Lc6Y(ebQAzQRGl^XkZKXMpb+]<pnVDZcd:WSv"
    secret-key = "dCS]l9<(u#4L]4$(6>CqJ]@NX-kvo+I5^&WPHDX+"

Client applications can be configured with the public key of one or more servers and thereby securely authenticate the server that is configured with the corresponding private key certificate. A client with a server's public key may also create a secure channel with the server. Client applications may be configured with a self-generated private key and thereby securely authenticate to a server that holds a copy of that that client's public key.

History

• The libbitcoin client-server protocol (API) is sometimes referred to as the Obelisk protocol, as this was the name of the first version of the server. In the first version the client API was contained within the libbitcoin-server library, which led to a dependency between client applications such as Bitcoin Explorer (bx), and the server library.

• In the summer of 2014 William Swanson redesigned the client library as libbitcoin-client. The first release of the independent library shipped as version 2.0 coincident with Bitcoin Explorer 2.0. This was a client to Obelisk, the original server application. As Obelisk was upgraded to Bitcoin Server (version 2.0) the client (version 2.1) was adapted to minor corresponding changes in the client-server API.

Dependencies (Version2)

• boost
• secp256k1
• sodium
• zmq
• czmq
• czmqpp
• libbitcoin

Dependencies (Version3)

• boost
• secp256k1
• zmq
• libbitcoin-protocol
• libbitcoin-system

See Also

• Libbitcoin