vendor/github.com/btcsuite/btcd/rpcclient/doc.go

   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.
   4
   5 /*
   6 Package rpcclient implements a websocket-enabled Bitcoin JSON-RPC client.
   7
   8 Overview
   9
  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).
  15
  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.
  20
  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.
  26
  27 Websockets vs HTTP POST
  28
  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
  32 notifications.
  33
  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.
  37
  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.
  42
  43 Synchronous vs Asynchronous API
  44
  45 The client provides both a synchronous (blocking) and asynchronous API.
  46
  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
  50 returns.
  51
  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.
  59
  60 Notifications
  61
  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!
  65
  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.
  69
  70 Notification Handlers
  71
  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.
  75
  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.
  80
  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.
  85
  86 Automatic Reconnection
  87
  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
  94 longer to complete.
  95
  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
  98 commands.
  99
 100 The automatic reconnection can be disabled by setting the DisableAutoReconnect
 101 flag to true in the connection config when creating the client.
 102
 103 Minor RPC Server Differences and Chain/Wallet Separation
 104
 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.
 111
 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.
 118
 119 Errors
 120
 121 There are 3 categories of errors that will be returned throughout this package:
 122
 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
 127     server
 128   - Errors returned from the remote RPC server like unimplemented commands,
 129     nonexistent requested blocks and transactions, malformed data, and incorrect
 130     networks
 131
 132 The first category of errors are typically one of ErrInvalidAuth,
 133 ErrInvalidEndpoint, ErrClientDisconnect, or ErrClientShutdown.
 134
 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.
 138
 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
 141 it.
 142
 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:
 146
 147   amount, err := client.GetBalance("")
 148   if err != nil {
 149         if jerr, ok := err.(*btcjson.RPCError); ok {
 150                 switch jerr.Code {
 151                 case btcjson.ErrRPCUnimplemented:
 152                         // Handle not implemented error
 153
 154                 // Handle other specific errors you care about
 155                 }
 156         }
 157
 158         // Log or otherwise handle the error knowing it was not one returned
 159         // from the remote RPC server.
 160   }
 161
 162 Example Usage
 163
 164 The following full-blown client examples are in the examples directory:
 165
 166  - bitcoincorehttp
 167    Connects to a bitcoin core RPC server using HTTP POST mode with TLS disabled
 168    and gets the current block count
 169  - btcdwebsockets
 170    Connects to a btcd RPC server using TLS-secured websockets, registers for
 171    block connected and block disconnected notifications, and gets the current
 172    block count
 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
 177 */
 178 package rpcclient