1 // Copyright (c) 2014-2017 The btcsuite developers
2 // Use of this source code is governed by an ISC
3 // license that can be found in the LICENSE file.
6 Package rpcclient implements a websocket-enabled Bitcoin JSON-RPC client.
10 This client provides a robust and easy to use client for interfacing with a
11 Bitcoin RPC server that uses a btcd/bitcoin core compatible Bitcoin JSON-RPC
12 API. This client has been tested with btcd (https://github.com/btcsuite/btcd),
13 btcwallet (https://github.com/btcsuite/btcwallet), and
14 bitcoin core (https://github.com/bitcoin).
16 In addition to the compatible standard HTTP POST JSON-RPC API, btcd and
17 btcwallet provide a websocket interface that is more efficient than the standard
18 HTTP POST method of accessing RPC. The section below discusses the differences
19 between HTTP POST and websockets.
21 By default, this client assumes the RPC server supports websockets and has
22 TLS enabled. In practice, this currently means it assumes you are talking to
23 btcd or btcwallet by default. However, configuration options are provided to
24 fall back to HTTP POST and disable TLS to support talking with inferior bitcoin
25 core style RPC servers.
27 Websockets vs HTTP POST
29 In HTTP POST-based JSON-RPC, every request creates a new HTTP connection,
30 issues the call, waits for the response, and closes the connection. This adds
31 quite a bit of overhead to every call and lacks flexibility for features such as
34 In contrast, the websocket-based JSON-RPC interface provided by btcd and
35 btcwallet only uses a single connection that remains open and allows
36 asynchronous bi-directional communication.
38 The websocket interface supports all of the same commands as HTTP POST, but they
39 can be invoked without having to go through a connect/disconnect cycle for every
40 call. In addition, the websocket interface provides other nice features such as
41 the ability to register for asynchronous notifications of various events.
43 Synchronous vs Asynchronous API
45 The client provides both a synchronous (blocking) and asynchronous API.
47 The synchronous (blocking) API is typically sufficient for most use cases. It
48 works by issuing the RPC and blocking until the response is received. This
49 allows straightforward code where you have the response as soon as the function
52 The asynchronous API works on the concept of futures. When you invoke the async
53 version of a command, it will quickly return an instance of a type that promises
54 to provide the result of the RPC at some future time. In the background, the
55 RPC call is issued and the result is stored in the returned instance. Invoking
56 the Receive method on the returned instance will either return the result
57 immediately if it has already arrived, or block until it has. This is useful
58 since it provides the caller with greater control over concurrency.
62 The first important part of notifications is to realize that they will only
63 work when connected via websockets. This should intuitively make sense
64 because HTTP POST mode does not keep a connection open!
66 All notifications provided by btcd require registration to opt-in. For example,
67 if you want to be notified when funds are received by a set of addresses, you
68 register the addresses via the NotifyReceived (or NotifyReceivedAsync) function.
72 Notifications are exposed by the client through the use of callback handlers
73 which are setup via a NotificationHandlers instance that is specified by the
74 caller when creating the client.
76 It is important that these notification handlers complete quickly since they
77 are intentionally in the main read loop and will block further reads until
78 they complete. This provides the caller with the flexibility to decide what to
79 do when notifications are coming in faster than they are being handled.
81 In particular this means issuing a blocking RPC call from a callback handler
82 will cause a deadlock as more server responses won't be read until the callback
83 returns, but the callback would be waiting for a response. Thus, any
84 additional RPCs must be issued an a completely decoupled manner.
86 Automatic Reconnection
88 By default, when running in websockets mode, this client will automatically
89 keep trying to reconnect to the RPC server should the connection be lost. There
90 is a back-off in between each connection attempt until it reaches one try per
91 minute. Once a connection is re-established, all previously registered
92 notifications are automatically re-registered and any in-flight commands are
93 re-issued. This means from the caller's perspective, the request simply takes
96 The caller may invoke the Shutdown method on the client to force the client
97 to cease reconnect attempts and return ErrClientShutdown for all outstanding
100 The automatic reconnection can be disabled by setting the DisableAutoReconnect
101 flag to true in the connection config when creating the client.
103 Minor RPC Server Differences and Chain/Wallet Separation
105 Some of the commands are extensions specific to a particular RPC server. For
106 example, the DebugLevel call is an extension only provided by btcd (and
107 btcwallet passthrough). Therefore if you call one of these commands against
108 an RPC server that doesn't provide them, you will get an unimplemented error
109 from the server. An effort has been made to call out which commmands are
110 extensions in their documentation.
112 Also, it is important to realize that btcd intentionally separates the wallet
113 functionality into a separate process named btcwallet. This means if you are
114 connected to the btcd RPC server directly, only the RPCs which are related to
115 chain services will be available. Depending on your application, you might only
116 need chain-related RPCs. In contrast, btcwallet provides pass through treatment
117 for chain-related RPCs, so it supports them in addition to wallet-related RPCs.
121 There are 3 categories of errors that will be returned throughout this package:
123 - Errors related to the client connection such as authentication, endpoint,
124 disconnect, and shutdown
125 - Errors that occur before communicating with the remote RPC server such as
126 command creation and marshaling errors or issues talking to the remote
128 - Errors returned from the remote RPC server like unimplemented commands,
129 nonexistent requested blocks and transactions, malformed data, and incorrect
132 The first category of errors are typically one of ErrInvalidAuth,
133 ErrInvalidEndpoint, ErrClientDisconnect, or ErrClientShutdown.
135 NOTE: The ErrClientDisconnect will not be returned unless the
136 DisableAutoReconnect flag is set since the client automatically handles
137 reconnect by default as previously described.
139 The second category of errors typically indicates a programmer error and as such
140 the type can vary, but usually will be best handled by simply showing/logging
143 The third category of errors, that is errors returned by the server, can be
144 detected by type asserting the error in a *btcjson.RPCError. For example, to
145 detect if a command is unimplemented by the remote RPC server:
147 amount, err := client.GetBalance("")
149 if jerr, ok := err.(*btcjson.RPCError); ok {
151 case btcjson.ErrRPCUnimplemented:
152 // Handle not implemented error
154 // Handle other specific errors you care about
158 // Log or otherwise handle the error knowing it was not one returned
159 // from the remote RPC server.
164 The following full-blown client examples are in the examples directory:
167 Connects to a bitcoin core RPC server using HTTP POST mode with TLS disabled
168 and gets the current block count
170 Connects to a btcd RPC server using TLS-secured websockets, registers for
171 block connected and block disconnected notifications, and gets the current
173 - btcwalletwebsockets
174 Connects to a btcwallet RPC server using TLS-secured websockets, registers
175 for notifications about changes to account balances, and gets a list of
176 unspent transaction outputs (utxos) the wallet can sign