The reference consists of two parts: ABI and API.
Much from the libcurl ABI description applies here too, see libcurl ABI.
ABI stands for Application Binary Interface and it determines such details as how functions are called and in which binary format information should be passed from one program component to the next (Wikipedia has it all).
The code is currently in beta stage and some updates could break ABI. You are advised to follow the development and upgrade your code from time to time until the project goes into a stable phase.
The version numbers of the library follow
Semantic versioning
scheme, i.e. each version consists of three numbers: MAJOR.MINOR.PATCH.
The major version 0 denotes beta stage. Except for major version 0, only
major version updates could (and usually do) break backwards compatibility.
In the beta stage also minor version updates could break ABI, whereas in the
usual case they are reserved for extensions and major bug fixes.
See Changelog.md
for the detailed history and changes introduced by each
version.
Whenever there are changes done to the library that will cause an ABI breakage, a soname major number of the library is bumped to a higher one. Again, except for beta. In fact, the soname number and the major version number should stay the same in the future. The history of soname bumps looks as follows:
- libbitcoinrpc.so.0, January 2016
The library API consists of five segments:
bitcoinrpc_global
bitcoinrpc_cl
bitcoinrpc_method
bitcoinrpc_resp
bitcoinrpc_err
Additionally, there is one function called bitcoinrpc_call()
.
See design document for a general overview.
The whole user interface is contained in the main header, so to use the library it is enough to
#include <bitcoinrpc.h>
What follows is a detailed description of each method and data structure within the library. For a quick and easy introduction to typical use cases, see tutorial and examples.
The following is the list of preprocessor constants defined in
the bitcoinrpc.h
header.
-
BITCOINRPC_LIBNAME
= "bitcoinrpc" -
BITCOINRPC_VERSION
Version string: "BITCOINRPC_VERSION_MAJOR.BITCOINRPC_VERSION_MINOR.BITCOINRPC_VERSION_PATCH" like: "0.1.0" or "2.31.11"
-
BITCOINTPC_VERSION_MAJOR
-
BITCOINTPC_VERSION_MINOR
-
BITCOINTPC_VERSION_PATCH
Integers specifying the major, minor version number and patch, respectively.
-
BITCOINRPC_VERSION_HEX
A 3-byte hexadecimal representation of the version, e.g. 0x000100 for version 0.1.0 and 0x010300 for version 1.3. This is useful in numeric comparisons, e.g.:
#if BITCOIN_VERSION_HEX >= 0x020100
/* Code specific to version 2.1 and above */
#endif
-
BITCOINRPC_USER_DEFAULT
= "" -
BITCOINRPC_PASS_DEFAULT
= "" -
BITCOINRPC_ADDR_DEFAULT
= "127.0.0.1" -
BITCOINRPC_PORT_DEFAULT
= 8332Defalut parameters of a RPC client.
-
BITCOINRPC_PARAM_MAXLEN
= 65 (64 bytes +'\0'
)Maximal length of a string that holds a client's parameter (user name, password or address), including the terminating
'\0'
character. The default value: 64 bytes, holds any SHA256 hash, so it is more than enough. -
BITCOINRPC_URL_MAXLEN
Maximal length of the server url:
"http://%s:%d" = 2*BITCOINRPC_PARAM_MAXLEN + 13
-
BITCOINRPC_ERRMSG_MAXLEN
Maximal length of error message reported via
bitcoinrpc_err_t
To handle bitcoin amounts correctly, it is advisable to operate internally
only on satoshi units (one hunder millionth of a bitcoin), and avoid floating
point arithmetic completely. Therefore, many functions in this library
take an argument that is of the type: bitcoinrpc_satoshi_t
, defined as
typedef unsigned long long int bitcoinrpc_satoshi_t;
Please, see: Proper Money Handling article at Bitcoin wiki.
The error codes are defined as enum type BITCOINRPCEcode
:
typedef enum {
BITCOINRPCE_OK, /* Success */
BITCOINRPCE_ALLOC, /* cannot allocate more memory */
BITCOINRPCE_ARG, /* wrong argument, e.g. NULL */
BITCOINRPCE_BUG, /* a bug in the library (please report) */
BITCOINRPCE_CHECK, /* see: bitcoinrpc_resp_check() */
BITCOINRPCE_CON, /* connection error */
BITCOINRPCE_CURLE, /* libcurl returned some error */
BITCOINRPCE_ERR, /* unspecific error */
BITCOINRPCE_JSON, /* error parsing json data */
BITCOINRPCE_SERV /* Bitcoin server returned error */
} BITCOINRPCEcode;
The data structure handling custom error messages has typedef:
bitcoinrpc_err_t
and its internals are visible to the user:
struct bitcoinrpc_err
{
BITCOINRPCEcode code;
char msg[BITCOINRPC_ERRMSG_MAXLEN];
};
typedef
struct bitcoinrpc_err
bitcoinrpc_err_t;
If code == BITCOINRPCE_OK
after calling a function that takes pointer to
bitcoinrpc_err_t
as an argument, then the error message msg
is irrelevant
(usually set to NULL
). On the other hand, if code != BITCOINRPCE_OK
,
then msg
contains some custom error message of length at most
BITCOINRPC_ERRMSG_MAXLEN
. If code == BITCOINRPCE_SERV
then the error
message is a string containing the error message returned by the server,
i.e. the call was successful, but the server could not process the call,
(e.g. due to wrong parameters or the wallet being locked).
Routines to initialise the global state of the library and to clean up the library's internal garbage at the end of the program.
-
BITCOINRPCEcode
bitcoinrpc_global_init(void)
The global initialisation function. Please call this function from your main thread before any other call.
Return:BITCOINRPCE_OK
in case of success. -
BITCOINRPCEcode
bitcoinrpc_global_cleanup(void)
The global cleanup function. Please call this function at the end of your program to collect library's internal garbage.
Return:BITCOINRPCE_OK
. -
BITCOINRPCEcode
bitcoinrpc_global_set_allocfunc( void* (* const f) (size_t size) )
Set a memory allocating function for the library routines (the default is just standard malloc). If
f == NULL
he function does nothing.
Return:BITCOINRPCE_OK
orBITCOINRPCE_ARG
, iff == NULL
. -
BITCOINRPCEcode
bitcoinrpc_global_set_freefunc( void (* const f) (void *ptr) )
Set a memory freeing function for the library routines (the default is just standard free). If
f == NULL
he function does nothing.
Return:BITCOINRPCE_OK
orBITCOINRPCE_ARG
, iff == NULL
.
Routines to handle RPC client.
-
bitcoinrpc_cl_t
Type definition of the RPC client data structure.
-
bitcoinrpc_cl_t*
bitcoinrpc_cl_init(void)
Initialise a new RPC client with default values:
BITCOINRPC_USER_DEFAULT
,BITCOINRPC_PASS_DEFAULT
etc.
Return: a newly allocated handle or NULL in case of error. -
bitcoinrpc_cl_t*
bitcoinrpc_cl_init_params(const char *user, const char *pass, const char *addr, const unsigned int port )
Initialise a new RPC client and set some parameters (may not be
NULL
; in that case the function returnsNULL
as well). The parameter values are copied, so the original pointers are no longer needed. At mostBITCOINRPC_PARAM_MAXLEN
chars are copied to store a parameter.
Return: a newly allocated handle or NULL in case of error. -
BITCOINRPCEcode
bitcoinrpc_cl_free(bitcoinrpc_cl_t *cl)
Free the handle. The pointer
cl
is set toNULL
after the function call.
Return:BITCOINRPCE_OK
. -
BITCOINRPCEcode
bitcoinrpc_cl_get_user(bitcoinrpc_cl_t *cl, char *buf)
-
BITCOINRPCEcode
bitcoinrpc_cl_get_pass(bitcoinrpc_cl_t *cl, char *buf)
-
BITCOINRPCEcode
bitcoinrpc_cl_get_addr(bitcoinrpc_cl_t *cl, char *buf)
-
BITCOINRPCEcode
bitcoinrpc_cl_get_port(bitcoinrpc_cl_t *cl, unsigned int *bufi)
Copy a value of the client
cl
parameter tobuf
. The buffer is assumed to contain at leastBITCOINRPC_PARAM_MAXLEN
chars. At mostBITCOINRPC_PARAM_MAXLEN
chars are copied.
Return:BITCOINRPCE_OK
orBITCOINRPCE_ARG
in case of wrong arguments. -
BITCOINRPCEcode
bitcoinrpc_cl_get_url(bitcoinrpc_cl_t \*cl, char \*buf)
Copy value to
buf
. The buffer is assumed to contain at leastBITCOINRPC_URL_MAXLEN
chars. At mostBITCOINRPC_URL_MAXLEN
chars are copied.
Return:BITCOINRPCE_OK
orBITCOINRPCE_ARG
in case of wrong arguments.
Routines to handle an RPC method.
The argument json_t *params
to functions below is always copied
to library internals and the original pointer is no longer needed
after the function returns. It is the obligation of the user to free
the original pointer by decreasing its reference count:
json_decref(params)
.
-
bitcoinrpc_method_t
Type definition of a method object.
-
BITCOINRPC_METHOD
The enum type storing RPC method names. See Bitcoin RPC reference.
typedef enum {
BITCOINRPC_METHOD_NONSTANDARD, /* reserved for possible */
/* user extensions */
BITCOINRPC_METHOD_GETBESTBLOCKHASH, /* getbestblockhash */
BITCOINRPC_METHOD_GETBLOCK, /* getblock */
BITCOINRPC_METHOD_GETBLOCKCHAININFO, /* getblockchaininfo */
BITCOINRPC_METHOD_GETBLOCKCOUNT, /* getblockcount */
BITCOINRPC_METHOD_GETBLOCKHASH, /* getblockhash */
BITCOINRPC_METHOD_GETCHAINTIPS, /* getchaintips */
BITCOINRPC_METHOD_GETDIFFICULTY, /* getdifficulty */
BITCOINRPC_METHOD_GETMEMPOOLINFO, /* getmempoolinfo */
BITCOINRPC_METHOD_GETRAWMEMPOOL, /* getrawmempool */
BITCOINRPC_METHOD_GETTXOUT, /* gettxout */
BITCOINRPC_METHOD_GETTXOUTPROOF, /* gettxoutproof */
BITCOINRPC_METHOD_GETTXOUTSETINFO, /* gettxoutsetinfo */
BITCOINRPC_METHOD_VERIFYCHAIN, /* verifychain */
BITCOINRPC_METHOD_VERIFYTXOUTPROOF, /* verifytxoutproof */
/* Control RPCs */
BITCOINRPC_METHOD_GETINFO, /* getinfo */
BITCOINRPC_METHOD_HELP, /* help */
BITCOINRPC_METHOD_STOP, /* stop */
/* Generating RPCs */
BITCOINRPC_METHOD_GENERATE, /* generate */
BITCOINRPC_METHOD_GETGENERATE, /* getgenerate */
BITCOINRPC_METHOD_SETGENERATE, /* setgenerate */
/* Mining RPCs */
BITCOINRPC_METHOD_GETBLOCKTEMPLATE, /* getblocktemplate */
BITCOINRPC_METHOD_GETMININGINFO, /* getmininginfo */
BITCOINRPC_METHOD_GETNETWORKHASHPS, /* getnetworkhashps */
BITCOINRPC_METHOD_PRIORITISETRANSACTION, /* prioritisetransaction */
BITCOINRPC_METHOD_SUBMITBLOCK, /* submitblock */
/* Network RPCs */
BITCOINRPC_METHOD_ADDNODE, /* addnode */
BITCOINRPC_METHOD_GETADDEDNODEINFO, /* getaddednodeinfo */
BITCOINRPC_METHOD_GETCONNECTIONCOUNT, /* getconnectioncount */
BITCOINRPC_METHOD_GETNETTOTALS, /* getnettotals */
BITCOINRPC_METHOD_GETNETWORKINFO, /* getnetworkinfo */
BITCOINRPC_METHOD_GETPEERINFO, /* getpeerinfo */
BITCOINRPC_METHOD_PING, /* ping */
/* Raw transaction RPCs */
BITCOINRPC_METHOD_CREATERAWTRANSACTION, /* createrawtransaction */
BITCOINRPC_METHOD_DECODERAWTRANSACTION, /* decoderawtransaction */
BITCOINRPC_METHOD_DECODESCRIPT, /* decodescript */
BITCOINRPC_METHOD_GETRAWTRANSACTION, /* getrawtransaction */
BITCOINRPC_METHOD_SENDRAWTRANSACTION, /* sendrawtransaction */
BITCOINRPC_METHOD_SIGNRAWTRANSACTION, /* signrawtransaction */
/* Utility RPCs */
BITCOINRPC_METHOD_CREATEMULTISIG, /* createmultisig */
BITCOINRPC_METHOD_ESTIMATEFEE, /* estimatefee */
BITCOINRPC_METHOD_ESTIMATEPRIORITY, /* estimatepriority */
BITCOINRPC_METHOD_VALIDATEADDRESS, /* validateaddress */
BITCOINRPC_METHOD_VERIFYMESSAGE, /* verifymessage */
/* Wallet RPCs */
BITCOINRPC_METHOD_ADDMULTISIGADDRESS, /* addmultisigaddress */
BITCOINRPC_METHOD_BACKUPWALLET, /* backupwallet */
BITCOINRPC_METHOD_DUMPPRIVKEY, /* dumpprivkey */
BITCOINRPC_METHOD_DUMPWALLET, /* dumpwallet */
BITCOINRPC_METHOD_ENCRYPTWALLET, /* encryptwallet */
BITCOINRPC_METHOD_GETACCOUNTADDRESS, /* getaccountaddress */
BITCOINRPC_METHOD_GETACCOUNT, /* getaccount */
BITCOINRPC_METHOD_GETADDRESSESBYACCOUNT, /* getaddressesbyaccount */
BITCOINRPC_METHOD_GETBALANCE, /* getbalance */
BITCOINRPC_METHOD_GETNEWADDRESS, /* getnewaddress */
BITCOINRPC_METHOD_GETRAWCHANGEADDRESS, /* getrawchangeaddress */
BITCOINRPC_METHOD_GETRECEIVEDBYACCOUNT, /* getreceivedbyaccount */
BITCOINRPC_METHOD_GETRECEIVEDBYADDRESS, /* getreceivedbyaddress */
BITCOINRPC_METHOD_GETTRANSACTION, /* gettransaction */
BITCOINRPC_METHOD_GETUNCONFIRMEDBALANCE, /* getunconfirmedbalance */
BITCOINRPC_METHOD_GETWALLETINFO, /* getwalletinfo */
BITCOINRPC_METHOD_IMPORTADDRESS, /* importaddress */
BITCOINRPC_METHOD_IMPORTPRIVKEY, /* importprivkey */
BITCOINRPC_METHOD_IMPORTWALLET, /* importwallet */
BITCOINRPC_METHOD_KEYPOOLREFILL, /* keypoolrefill */
BITCOINRPC_METHOD_LISTACCOUNTS, /* listaccounts */
BITCOINRPC_METHOD_LISTADDRESSGROUPINGS, /* listaddressgroupings */
BITCOINRPC_METHOD_LISTLOCKUNSPENT, /* listlockunspent */
BITCOINRPC_METHOD_LISTRECEIVEDBYACCOUNT, /* listreceivedbyaccount */
BITCOINRPC_METHOD_LISTRECEIVEDBYADDRESS, /* listreceivedbyaddress */
BITCOINRPC_METHOD_LISTSINCEBLOCK, /* listsinceblock */
BITCOINRPC_METHOD_LISTTRANSACTIONS, /* listtransactions */
BITCOINRPC_METHOD_LISTUNSPENT, /* listunspent */
BITCOINRPC_METHOD_LOCKUNSPENT, /* lockunspent */
BITCOINRPC_METHOD_MOVE, /* move */
BITCOINRPC_METHOD_SENDFROM, /* sendfrom */
BITCOINRPC_METHOD_SENDMANY, /* sendmany */
BITCOINRPC_METHOD_SENDTOADDRESS, /* sendtoaddress */
BITCOINRPC_METHOD_SETACCOUNT, /* setaccount */
BITCOINRPC_METHOD_SETTXFEE, /* settxfee */
BITCOINRPC_METHOD_SIGNMESSAGE, /* signmessage */
BITCOINRPC_METHOD_WALLETLOCK, /* walletlock */
BITCOINRPC_METHOD_WALLETPASSPHRASE, /* walletpassphrase */
BITCOINRPC_METHOD_WALLETPASSPHRASECHANGE /* walletpassphrasechange */
} BITCOINRPC_METHOD;
-
bitcoinrpc_method_t *
bitcoinrpc_method_init(const BITCOINRPC_METHOD m)
Initialise a new bare method.
Return: a newly allocated method orNULL
in case of error. -
bitcoinrpc_method_t *
bitcoinrpc_method_init_params(const BITCOINRPC_METHOD m, json_t * const params)
Initialise a new method with
json_t
array:params
. Ifparams == NULL
, this is the same asbitcoinrpc_method_init()
.
Return: a newly allocated method orNULL
in case of error. -
BITCOINRPCEcode
bitcoinrpc_method_free(bitcoinrpc_method_t *method)
Destroy the method and set the pointer
method
toNULL
. Return:BITCOINRPCE_OK
. -
BITCOINRPCEcode
bitcoinrpc_method_set_params(bitcoinrpc_method_t *method, json_t *params)
Set a new
json_t
object as method parameters.
Return:BITCOINRPCE_OK
, orBITCOINRPCE_JSON
ifparams
cannot be parsed. -
BITCOINRPCEcode
bitcoinrpc_method_get_params(bitcoinrpc_method_t *method, json_t **params)
Get a deep copy of the method's parameters and store it in
params
.
Return:BITCOINRPCE_OK
, orBITCOINRPCE_JSON
ifparams
cannot be copied by libjansson. -
BITCOINRPCEcode
bitcoinrpc_method_setname(bitcoinrpc_method_t *method, char *name)
Set a custom name for the method. Works only if method is initialised with BITCOINRPC_METHOD_NONSTANDARD, otherwise returns BITCOINRPCE_ERR. The pointer to str is copied, not the string itself. It is the obligation of the user, to keep the str available and free it, when no longer needed. Return:
BITCOINRPCE_OK
orBITCOINRPCE_ERR
.
Store JSON responses from the server.
-
bitcoinrpc_resp_t
Type definition of the response struct.
-
bitcoinrpc_resp_t *
bitcoinrpc_resp_init(void)
Initialise a new bare response.
Return: a newly allocated response orNULL
in case of error. -
BITCOINRPCEcode
bitcoinrpc_resp_free(bitcoinrpc_resp_t *resp)
Destroy the response
resp
and set the pointer toNULL
.
Return:BITCOINRPCE_OK
. -
json_t *
bitcoinrpc_resp_get(bitcoinrpc_resp_t *resp)
Get a deep copy of the JSON object representing the response from the server.
Return: a newly allocatedjson_t
object orNULL
in case of error. -
BITCOINRPCEcode
bitcoinrpc_resp_check(bitcoinrpc_resp_t *resp, bitcoinrpc_method_t *method)
Check, if the
resp
comes as a result of callingmethod
. This check is already performed bybitcoinrpc_call()
.
Returns:BITCOINRPCE_OK
orBITCOINRPCE_CHECK
, if check fails.
BITCOINRPCEcode
bitcoinrpc_call(bitcoinrpc_cl_t * cl, bitcoinrpc_method_t * method, bitcoinrpc_resp_t *resp, bitcoinrpc_err_t *e)
Use client cl
to call the server with method
. Save response in resp
and report errors. If e == NULL
, it is ignored.
Return: BITCOINRPCE_OK
in case of success, or other error code.
last updated: 2016-02-06