Difference between revisions of "Libbitcoin Client"

From Bitcoin Wiki
Jump to: navigation, search
(Update references.)
m
(25 intermediate revisions by the same user not shown)
Line 1: Line 1:
The [https://github.com/libbitcoin/libbitcoin-client libbitcoin-client] library provides an abstraction over the low level networking calls required to communicate with [[Libbitcoin_Server|libbitcoin-server (BS)]]. The server application is currently monolithic (not divided into library and executable) so there is no analog to the libbitcoin-client API for a server.
+
The [https://github.com/libbitcoin/libbitcoin-client libbitcoin-client] library provides an abstraction over the low level networking calls required to communicate with [[Bitcoin_Server|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|Bitcoin Server]].
  
==Example==
+
==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 <iostream>
 
  #include <czmq++/czmqpp.hpp>
 
  #include <czmq++/czmqpp.hpp>
Line 13: Line 52:
 
     if (argc < 2 || socket.connect(argv[1]) < 0)
 
     if (argc < 2 || socket.connect(argv[1]) < 0)
 
     {
 
     {
         std::cerr << "server argument required" << std::endl;
+
         std::cerr << "server address required" << std::endl;
 
         return 1;
 
         return 1;
 
     }
 
     }
Line 21: Line 60:
 
     auto obelisk = std::make_shared<bc::client::obelisk_codec>(message);
 
     auto obelisk = std::make_shared<bc::client::obelisk_codec>(message);
 
    
 
    
     const auto error_handler = [](const std::error_code& code)
+
     const auto error_handler = [](const std::error_code& ec)
 
     {
 
     {
         std::cout << "error: " << code.message() << std::endl;
+
         std::cerr << "error: " << ec.message() << std::endl;
 
     };
 
     };
 
    
 
    
Line 59: Line 98:
 
The API incorporates [http://curvezmq.org CurveZMQ], "An authentication and encryption protocol for ZeroMQ."<ref>[http://curvezmq.org CurveZMQ - Security for ZeroMQ]</ref><ref>[http://rfc.zeromq.org/spec:26 CurveZMQ Authentication and Encryption Protoco]</ref> CurveZMQ is based on [http://curvecp.org CurveCP] and [http://nacl.cr.yp.to NaCl], providing fast, secure elliptic-curve crypto.<ref>[http://cr.yp.to/highspeed/coolnacl-20120725.pdf "The security impact of a new cryptographic library" - Daniel J. Bernstein et. al.]</ref>
 
The API incorporates [http://curvezmq.org CurveZMQ], "An authentication and encryption protocol for ZeroMQ."<ref>[http://curvezmq.org CurveZMQ - Security for ZeroMQ]</ref><ref>[http://rfc.zeromq.org/spec:26 CurveZMQ Authentication and Encryption Protoco]</ref> CurveZMQ is based on [http://curvecp.org CurveCP] and [http://nacl.cr.yp.to NaCl], providing fast, secure elliptic-curve crypto.<ref>[http://cr.yp.to/highspeed/coolnacl-20120725.pdf "The security impact of a new cryptographic library" - Daniel J. Bernstein et. al.]</ref>
  
Private key certificates are self-generated as [http://rfc.zeromq.org/spec:4 ZPL (ZeroMQ Property Language)] encoded files with public and secret key properties. The keys are [http://rfc.zeromq.org/spec:32 Z85 - (ZeroMQ Base-85 Encoding Algorithm)] encoded elliptic curve points. Keys can be fabricated by Bitcoin Explorer (BX)<ref>[https://github.com/libbitcoin/libbitcoin-explorer/wiki/bx-cert-new Bitcoin Explorer cert-new command.]</ref> as follows.
+
Private key certificates are self-generated as [http://rfc.zeromq.org/spec:4 ZPL (ZeroMQ Property Language)] encoded files with public and secret key properties. The keys are [http://rfc.zeromq.org/spec:32 Z85 - (ZeroMQ Base-85 Encoding Algorithm)] encoded elliptic curve points. Keys can be fabricated by Bitcoin Explorer (bx)<ref>[https://github.com/libbitcoin/libbitcoin-explorer/wiki/bx-cert-new Bitcoin Explorer cert-new command.]</ref> as follows (version 2).
  
 
  $ bx cert-new citizen4.private
 
  $ bx cert-new citizen4.private
Line 73: Line 112:
 
     secret-key = "dCS]l9<(u#4L]4$(6>CqJ]@NX-kvo+I5^&WPHDX+"
 
     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<ref>[https://github.com/libbitcoin/libbitcoin-explorer/wiki/Configuration-Settings#default-configuration-settings BX Configuration Settings]</ref> and thereby securely authenticate the server that is configured with the corresponding private key certificate<ref>[https://github.com/libbitcoin/libbitcoin-server/wiki/Configuration-Settings#configuration-settings BS Configuration Settings]</ref>. 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<ref>[https://github.com/libbitcoin/libbitcoin-explorer/wiki/Configuration-Settings#default-configuration-settings BX Configuration Settings]</ref> and thereby securely authenticate to a server that holds a copy of that that client's public key<ref>[https://github.com/libbitcoin/libbitcoin-server/wiki/Configuration-Settings#configuration-settings BS Configuration Settings]</ref>.
+
Client applications can be configured with the public key of one or more servers<ref>[https://github.com/libbitcoin/libbitcoin-explorer/wiki/Configuration-Settings#default-configuration-settings Bitcoin Explorer Configuration Settings]</ref> and thereby securely authenticate the server that is configured with the corresponding private key certificate<ref>[https://github.com/libbitcoin/libbitcoin-server/wiki/Configuration-Settings#configuration-settings Bitcoin Server Configuration Settings]</ref>. 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==
 
==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 [[Libbitcoin_Explorer|Bitcoin Explorer (BX)]], and the server library.
+
* 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|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. With few exceptions (fetch-stealth and watch-address), the client is compatible with both Obelisk and Bitcoin Server.
+
* 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==
+
==Dependencies (Version2)==
* [[Libbitcoin_Common|libbitcoin]]
+
* [http://www.boost.org boost]
 
* [https://github.com/bitcoin/secp256k1 secp256k1]
 
* [https://github.com/bitcoin/secp256k1 secp256k1]
 
* [https://github.com/jedisct1/libsodium sodium]
 
* [https://github.com/jedisct1/libsodium sodium]
Line 87: Line 126:
 
* [https://github.com/zeromq/czmq czmq]
 
* [https://github.com/zeromq/czmq czmq]
 
* [https://github.com/zeromq/czmqpp czmqpp]
 
* [https://github.com/zeromq/czmqpp czmqpp]
 +
* [[Libbitcoin_Common|libbitcoin]]
 +
 +
==Dependencies (Version3)==
 +
* [http://www.boost.org boost]
 +
* [https://github.com/bitcoin/secp256k1 secp256k1]
 +
* [https://github.com/zeromq/libzmq zmq]
 +
* [[Libbitcoin_Protocol|libbitcoin-protocol]]
 +
* [[Libbitcoin_Common|libbitcoin]]
  
 
==See Also==
 
==See Also==
Line 92: Line 139:
  
 
==References==
 
==References==
 +
 +
[[Category:Clients]]
 +
[[Category:Open Source]]
 +
[[Category:Software‏‎]]

Revision as of 20:12, 8 March 2017

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."[1] ØMQ sits directly on sockets and, "Carries messages across inproc, IPC, TCP, TIPC, multicast."[2] The API supports the pub-sub pattern[3] (e.g. monitoring Bitcoin addresses) and the router-dealer pattern[4] (e.g. requesting stealth transactions).

Authentication and Encryption

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

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)[8] 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[9] and thereby securely authenticate the server that is configured with the corresponding private key certificate[10]. 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)

Dependencies (Version3)

See Also

References