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

   1 // Copyright (c) 2015 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 btcjson provides primitives for working with the bitcoin JSON-RPC API.
   7
   8 Overview
   9
  10 When communicating via the JSON-RPC protocol, all of the commands need to be
  11 marshalled to and from the the wire in the appropriate format.  This package
  12 provides data structures and primitives to ease this process.
  13
  14 In addition, it also provides some additional features such as custom command
  15 registration, command categorization, and reflection-based help generation.
  16
  17 JSON-RPC Protocol Overview
  18
  19 This information is not necessary in order to use this package, but it does
  20 provide some intuition into what the marshalling and unmarshalling that is
  21 discussed below is doing under the hood.
  22
  23 As defined by the JSON-RPC spec, there are effectively two forms of messages on
  24 the wire:
  25
  26   - Request Objects
  27     {"jsonrpc":"1.0","id":"SOMEID","method":"SOMEMETHOD","params":[SOMEPARAMS]}
  28     NOTE: Notifications are the same format except the id field is null.
  29
  30   - Response Objects
  31     {"result":SOMETHING,"error":null,"id":"SOMEID"}
  32     {"result":null,"error":{"code":SOMEINT,"message":SOMESTRING},"id":"SOMEID"}
  33
  34 For requests, the params field can vary in what it contains depending on the
  35 method (a.k.a. command) being sent.  Each parameter can be as simple as an int
  36 or a complex structure containing many nested fields.  The id field is used to
  37 identify a request and will be included in the associated response.
  38
  39 When working with asynchronous transports, such as websockets, spontaneous
  40 notifications are also possible.  As indicated, they are the same as a request
  41 object, except they have the id field set to null.  Therefore, servers will
  42 ignore requests with the id field set to null, while clients can choose to
  43 consume or ignore them.
  44
  45 Unfortunately, the original Bitcoin JSON-RPC API (and hence anything compatible
  46 with it) doesn't always follow the spec and will sometimes return an error
  47 string in the result field with a null error for certain commands.  However,
  48 for the most part, the error field will be set as described on failure.
  49
  50 Marshalling and Unmarshalling
  51
  52 Based upon the discussion above, it should be easy to see how the types of this
  53 package map into the required parts of the protocol
  54
  55   - Request Objects (type Request)
  56     - Commands (type <Foo>Cmd)
  57     - Notifications (type <Foo>Ntfn)
  58   - Response Objects (type Response)
  59     - Result (type <Foo>Result)
  60
  61 To simplify the marshalling of the requests and responses, the MarshalCmd and
  62 MarshalResponse functions are provided.  They return the raw bytes ready to be
  63 sent across the wire.
  64
  65 Unmarshalling a received Request object is a two step process:
  66   1) Unmarshal the raw bytes into a Request struct instance via json.Unmarshal
  67   2) Use UnmarshalCmd on the Result field of the unmarshalled Request to create
  68      a concrete command or notification instance with all struct fields set
  69      accordingly
  70
  71 This approach is used since it provides the caller with access to the additional
  72 fields in the request that are not part of the command such as the ID.
  73
  74 Unmarshalling a received Response object is also a two step process:
  75   1) Unmarhsal the raw bytes into a Response struct instance via json.Unmarshal
  76   2) Depending on the ID, unmarshal the Result field of the unmarshalled
  77      Response to create a concrete type instance
  78
  79 As above, this approach is used since it provides the caller with access to the
  80 fields in the response such as the ID and Error.
  81
  82 Command Creation
  83
  84 This package provides two approaches for creating a new command.  This first,
  85 and preferred, method is to use one of the New<Foo>Cmd functions.  This allows
  86 static compile-time checking to help ensure the parameters stay in sync with
  87 the struct definitions.
  88
  89 The second approach is the NewCmd function which takes a method (command) name
  90 and variable arguments.  The function includes full checking to ensure the
  91 parameters are accurate according to provided method, however these checks are,
  92 obviously, run-time which means any mistakes won't be found until the code is
  93 actually executed.  However, it is quite useful for user-supplied commands
  94 that are intentionally dynamic.
  95
  96 Custom Command Registration
  97
  98 The command handling of this package is built around the concept of registered
  99 commands.  This is true for the wide variety of commands already provided by the
 100 package, but it also means caller can easily provide custom commands with all
 101 of the same functionality as the built-in commands.  Use the RegisterCmd
 102 function for this purpose.
 103
 104 A list of all registered methods can be obtained with the RegisteredCmdMethods
 105 function.
 106
 107 Command Inspection
 108
 109 All registered commands are registered with flags that identify information such
 110 as whether the command applies to a chain server, wallet server, or is a
 111 notification along with the method name to use.  These flags can be obtained
 112 with the MethodUsageFlags flags, and the method can be obtained with the
 113 CmdMethod function.
 114
 115 Help Generation
 116
 117 To facilitate providing consistent help to users of the RPC server, this package
 118 exposes the GenerateHelp and function which uses reflection on registered
 119 commands or notifications, as well as the provided expected result types, to
 120 generate the final help text.
 121
 122 In addition, the MethodUsageText function is provided to generate consistent
 123 one-line usage for registered commands and notifications using reflection.
 124
 125 Errors
 126
 127 There are 2 distinct type of errors supported by this package:
 128
 129   - General errors related to marshalling or unmarshalling or improper use of
 130     the package (type Error)
 131   - RPC errors which are intended to be returned across the wire as a part of
 132     the JSON-RPC response (type RPCError)
 133
 134 The first category of errors (type Error) typically indicates a programmer error
 135 and can be avoided by properly using the API.  Errors of this type will be
 136 returned from the various functions available in this package.  They identify
 137 issues such as unsupported field types, attempts to register malformed commands,
 138 and attempting to create a new command with an improper number of parameters.
 139 The specific reason for the error can be detected by type asserting it to a
 140 *btcjson.Error and accessing the ErrorCode field.
 141
 142 The second category of errors (type RPCError), on the other hand, are useful for
 143 returning errors to RPC clients.  Consequently, they are used in the previously
 144 described Response type.
 145 */
 146 package btcjson